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Introduction 

This 



chapter contains the following sections: 

"Introduction" (this section) describes the ES/PEX releases and 
graphics standards. 

"What is PEX?" describes the X Model, the PHIGS Model, and the 
PEX Model. 

"Functional Overview" contains a general discussion of the ES/PEX 
function types supported by the ES V Workstation. 

"PHIGS Functions" contains a list of all of the PHIGS and PHIGS PLUS 
functions and identifies those that are not currently supported. 

"Compatibility with Prior Releases" describes the porting process for 
running applications written prior to the 2.0 Release. 

"OPEN XPHIGS" describes the OPEN XPHIGS function. 

"OPEN PEX" describes the OPEN PEX function. 

"OPEN WORKSTATION" describes the OPEN WORKSTATION 

function. 

"GENERALIZED DRAWING PRIMITIVE" describes the GDPs, 
which are used to create 2D elements. 

"GENERALIZED DRAWING PRIMITIVE 3" describes the GDP3s, 
which are used to create 3D elements. 

"GENERALIZED STRUCTURE ELEMENT' describes the GSEs, 
which are used to create implementation-dependent structure 
elements. 

"SET HLHSR ID" describes the SET HLHSR ID function. 

"SET HLHSR MODE" describes the SET HLHSR MODE function. 

"PHIGS Input with ES V Devices" describes PHIGS input and 
contains examples for the knob box, button box, and Spaceball. 

"Function Numbers" contains a list of the function numbers with the 
corresponding function name. Function numbers are returned with 
error messages. 

"Error Messages" contains a list of the error numbers with the corre- 
sponding error description. Error numbers are returned with error 
messages. 
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• "PHIGS Tables" contains the PHIGS Description Table, PHIGS PLUS 
Description Table, PHIGS Workstation Description Table, and the 
PHIGS PLUS Workstation Description Table. 

• "C and FORTRAN Bindings" contains a list of the C and FORTRAN 
bindings for the PHIGS and PHIGS PLUS functions. 

• "Sample Programs" contains four programs implemented in two dif- 
ferent ways: one way using the Xlib calls, and the other way using the 
Motif Graphical User Interface. 

• "Bibliography" contains a list of PEX references. 

This chapter assumes that the reader has a working knowledge of the C 
programming language, an understanding of the X programming environ- 
ment, a general understanding of PHIGS, and knowledge of computer graph- 
ics principles. 

ES/PEX Releases 

The ES V Workstation supports PEX (PHIGS Extension to X), which gives the 
user access to the X Window System, the PHIGS (Programmer's Hierarchical 
Interactive Graphics System) standard interface, and the proposed 
PHIGS PLUS (PHIGS Plus Lumiere und Surfaces) standard. 

PEX has not yet been released by the X Consortium. Evans & Sutherland 
is a sponsor of the X Consortium, and ES/PEX is based on the PEX-SI from 
the X Consortium using the PEX protocol level 5. OP. Evans & Sutherland will 
continue to follow the PEX development, and, upon release of the PEX exten- 
sion to public domain, will provide a PEX-compatible server on the ES V 
Workstation. 

Since the Application Programmers Interface (API) for the C language to 
PHIGS and PHIGS PLUS is not yet an official standard, the PEX development 
work by the X Consortium was initially done using the Sun-defined C lan- 
guage interface. This has been updated to include the current drafts and those 
comments that are likely to be accepted. This is also the interface currently 
used by ES/PEX. 

It should be emphasized that PEX is still in the development period. 
Therefore, programs that run under the current release of ES/PEX may have 
to be recompiled or altered for future releases. 
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Graphics Standards 



There are a number of different computer graphics products that are referred 
to as "standards." This section discusses several of these and explains how 
they relate to the ESV Workstation software. 



ISO Standards 



International Organization for Standardization (ISO) standards are developed 
by representatives of nations that are a part of ISO. This means that for a par- 
ticular standard, the representatives attending from a country usually come 
from the national standard organization with responsibility for that particular 
area. 

The United States is represented by ANSI. If a standard is being developed 
for computer graphics, the group within ANSI that is responsible for computer 
graphics will send representatives to ISO computer graphics standards 
meetings. 

Several steps are involved the development process of an ISO standard: 

• New Work Item (NWI) 

A standard always starts as a NWI, which is a proposal for 
development of a standard. If the NWI is accepted by the member 
nations, the task of developing a standard is assigned to a Standing 
Committee (SC) Working Group (WG). 

• Draft 

The SC/WG produces a draft of the standard. Very often the draft will 
exist before the NWI is approved, which was the case with both PHIGS 
and PHIGS PLUS. The SCs and WGs have numbers assigned. For 
example, the responsibilities for graphics standards is in SC24/WG2. 

• Committee Draft (CD) 

After a draft is produced by the WG, it is submitted as a CD and is 
voted on by the member nations. After the vote, comments are 
processed by the WG and changes are made to the draft. 

• Draft International Standard (DIS) 

If the vote is for approval and the changes are not substantial, the CD 
is submitted as a DIS. If substantial changes are made as a result of the 
comments, the document may go through a second CD ballot before 
proceeding on to DIS. The DIS vote can only result in editorial 
changes to the standard. 
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After the voting is complete, the editorial changes are made and the 
document is submitted as an IS. 

The PHIGS functional description is an ISO standard (ISO 9592-1:1988), 
and the PHIGS PLUS functional description (ISO 9592-4: 199x) is currently 
under development in ISO as a standard. The PHIGS standard is a functional 
description that is independent of any language and is composed of the 
following parts: 

• The PHIGS functional description (Part 1), 

• The archive file format description (Part 2), 

• The clear text encoding of the archive file (Part 3), and 

• The proposed PHIGS PLUS functional description (Part 4). 

Along with these four parts is another standard called the language 
bindings for PHIGS. A language binding is a specific description of how the 
PHIGS functional description is to be represented in a particular programming 
language. Each of these bindings goes through the standardization process 
just like PHIGS and PHIGS PLUS. 

Figure 1-1 shows the position of PHIGS and related standards in the 
development process of an ISO standard. 

NWI draft CD — DIS —IS 

PHIGS PLUS C PHIGS PLUS PHIGS 

PHIGS C PHIGS FORTRAN 

PHIGS Ada 



No public vote required to progress 

Public vote required to progress 

Figure 1-1. Approval steps for ISO standards 

ANSI Standards 

The approval steps for an American National Standards Institute (ANSI) stan- 
dard are very similar to the ISO steps. There is also an ANSI procedure for par- 
ticipation in the development of ISO standards. Like ISO, all ANSI standards 
start with an NWI, followed by a draft, a draft proposed American National 
Standard (dpANS), and finally an American National Standard (ANS). 

ANSI forms committees in different areas called Accredited Standards 
Committees (ASC) and assigns them a letter and number. These committees 
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have subgroups responsible for different areas of standards development. A 
subgroup may be broken down into task groups for specific standards work. 

PHIGS and PHIGS PLUS fall under task group 1 of the subgroup on 
Computer Graphics Standards (H3) of the committee on Information 
Processing Systems (X3). The full designation for the ASC on the 
development and maintenance of PHIGS and PHIGS PLUS is X3H3.1. 
However, since PHIGS PLUS is being developed in ISO, the work of the ASC 
task group is to provide input and comment to X3 as to how the U.S. should 
vote on PHIGS PLUS. The X3H3.1 group also provides representatives to the 
ISO SC24/WG2 meetings. 

Evans & Sutherland has representatives on ASC X3H3.1 PHIGS PLUS and 
X3H3.2 Computer Graphics Reference Models, as well as representatives on 
ISO SC24/WG2 PHIGS PLUS. 

PHIGS was developed as an ANS but was recently replaced by the ISO 
version, which is identical. This means that there is now only one standard 
and that the responsibility for maintenance of PHIGS is in ISO. 

Also of interest is the X Window System standard. This is not being 
developed in ISO but rather in the ANSI ASC task group X3H3.6. This standard 
is called the X Window Data Stream Definition and is divided into three parts: 

• Functional Specification, 

• Data Stream Encoding, and 

• KEYSYM Encoding. 

The X Window Data Stream Definition has just completed the dpANS 
stage. 

U.S. Government Standards 

These are not standards that have been developed by the U.S. Government, 
but rather standards that have been accepted for specification in government 
contracts. 

• Federal Information Processing Standard (FIPS) 

A FIPS is a requirement for inclusion of a particular standard in U.S. 
Government procurement contracts. PHIGS is not currently a FIPS. 

• Military Specifications (Milspec) 

A Milspec is a requirement for inclusion of a particular standard in a 
military procurement specification. PHIGS is not yet a Milspec. 

Industry Standards 

The term "industry standard" applied to a product implies the wide-spread use 
of that product in the industry. The term can lead to some confusion because 
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anyone can claim to have an "industry standard." There are two industry stan- 
dards of particular interest on the ESV Workstation. 

• X Window System 

The X Window System consists of a protocol definition and an imple- 
mentation of that protocol. The protocol is maintained by the X Con- 
sortium, which consists of members from different areas of industry 
and education, and the implementation is maintained by MIT. The 
current level of the X Window System is XI 1R4, and this is the ver- 
sion currently supported on the ESV Workstation. 

• PEX 

The X Window System specification allows for extensions to be add- 
ed. There are several extensions that come with the release from MIT. 
Several years ago, a PEX Consortium was formed to define a protocol 
for an extension to the X Window System that would work with 
PHIGS and PHIGS PLUS applications. Sun Microsystems was selected 
to implement the protocol, and the implementation is currently in re- 
lease to the X Consortium members. 

Evans & Sutherland is a member of the PEX Consortium. ES/PEX is 
currently based on the preliminary release Rl. 

There are no current plans to process PEX as an ANSI or ISO standard. 
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ESV Workstation Conformance to PfflGS Standards 

The native graphics language of the ESV Series Workstations is 
PHIGS/PHIGS PLUS. ES/PEX is Evans & Sutherland's implementation of the 
PEX-SI Release from the X Consortium. The PEX-SI is based on the PHIGS 
functional description (ISO/IEC 9592-1:1989) and the PHIGS PLUS updated 
draft functional description (ISO/IEC SC24-N454(20 March 90)). 

The ES/PEX implementation provides the ISO Standard (ISO/IEC 9593- 
4: 1990) PHIGS FORTRAN (F77 subset) binding and the ISO (DP on ISO/IEC 
9593-4: 199x) PHIGS C binding. Future releases of the PHIGS C binding will 
be modified, as needed, to match the ISO DIS when it becomes available. 

Released standards do not yet exist for PHIGS PLUS, or PHIGS PLUS 
bindings to FORTRAN and C. ES/PEX provides a PHIGS PLUS C binding 
based on PEX-SI functionality as it matches the Working Draft amendments 
to ISO/IEC 9593-4: 199x. There is no current draft proposal for PHIGS PLUS 
FORTRAN. ES/PEX provides a PHIGS PLUS FORTRAN binding based on 
PEX-SI functionality as it matches the SunPHIGS/PIIIGS PLUS extensions. 

Standards Conformance Tests do not exist for PHIGS C, PHIGS PLUS C 
or for PHIGS PLUS FORTRAN. The ES/PEX implementation of PHIGS 
FORTRAN has not been submitted for Conformance Testing pending 
completion of the following functionality: cell arrays, CIELUV color model, 
incremental spatial search, modelling clip, metafiles, and stroke device. 
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What is pex? 



The X Window System is a publicly available protocol that supports 2D 
graphics. PEX is an extension to the X Window System which allows X to 
support 3D graphics and gives a user application access to the PHIGS and 
PHIGS PLUS functions. To understand PEX, we must first look at the X Model 
and the PHIGS Model. Figure 1-2 shows a simplified schematic of the X Mod- 
el, figure 1-3 shows a simplified schematic of the PHIGS Model, and figure 
1-4 shows a simplified schematic of the PEX Model. 



The X Model 



The X Model is divided into two parts: the client and the server. The server 
controls the graphics display and is the interface between the client and the 
graphics display. The client is a user application that may or may not be run- 
ning on the same system as the graphics display. 

The X Window System defines the device-independent/?r<9toc<9/ between 
the client and the server. Xlib and the X server are sample implementations 
of the X protocol on a specific system, such as the ES V Workstation, and are 
device-dependent. A user application calls the Xlib functions, which, in turn, 
generate data packets defined by the X protocol. The X server translates these 
data packets into commands that control the graphics display. 



The PHIGS Model 



PHIGS is a functional specification defining the interface between a user 
application and the graphics system that displays the application. PHIGS is 
device-independent. 

PHIGS creates application data structures that are stored in an area called 
the central store structure (CSS), which is also created by PHIGS. The data 
structures can be posted to one or more workstations, or devices, which are 
also created by PHIGS. A workstation may or may not be equivalent to a hard- 
ware system, such as the ES V Workstation. 



The PEX Model 



The X Window System permits the addition of extensions, which are also 
protocols. PEX is one extension. Other extensions on the ES V Workstation 
include the X Input extension, X Picking extension, X Overlay extension, and 
the X Multiscreen extension. PEX is an addition to the X protocol which gives 
a user application access to the X Window System through PHIGS and PHIGS 
PLUS functions. 

With the PEX, X Input, and X Picking extensions added to the X Window 
System, a user application has access to the Xlib functions, the PHIGS and 
PHIGS PLUS functions, and the X Input, X Picking, X Overlay, and 
X Multiscreen functions. An application call to a PHIGS or PHIGS PLUS 
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function is translated into a PEX protocol data packet which is sent to the X 
server. The X server recognizes the data packet as being from PEX and 
transfers it to the PEX routines in the X server for processing. The X Input, X 
Picking, X Overlay, X Multiscreen data packets are processed in a similar 
manner. 

If a PHIGS workstation is created on the ES V Workstation, the display 
surface of the PHIGS workstation will be mapped to an X window that is 
opened on the ES V Workstation. If the PHIGS workstation is closed, the X 
window will remain open but will revert to a 2D window. 



ESV Workstation Reference Manual [2.0] 1 - 9 



ES/PEX 



c 



Client 




X Protocol 



Server 





c 



L 



\ 



w 
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Functional Overview 

PHIGS and PHIGS PLUS capabilities are expressed by functions and the pa- 
rameter ranges of those functions. It should be understood that not all imple- 
mentations will be able to support all capabilities. The PHIGS standard 
outlines a set of minimum support criteria; and, depending on the implemen- 
tation, the parameter range provided by a specific implementation may ex- 
ceed the minimum criteria. 

The following list is a very generalized outline of the PHIGS and 
PHIGS PLUS functions not currently supported by the ES V Workstation. 

B-spline curves and surfaces 

Cell arrays 

Curve and surface approximation by subdivision 

Incremental spatial search 

Input stroke device 

Line width 

Metafiles 

Model space clip 

Patterning and hatching of fill areas 

Normal or dot product shading 

Raster or polygon text 

Text precision other than stroke 

Trimming curves 

Interior Styles 

The ESV Workstation supports interior styles Solid, Empty, and Hollow. 

Light Source Types and Table Indices 

The ESV Workstation supports the following light source types: 

• ambient (1) 

• directional (2) 

• positional (3) 

• spot (4) 
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Linetypes and Edgetypes £ 

The ES V Workstation supports the following four required edgetypes and 
linetypes: 

• solid (1) 

• dashed (2) 

• dotted (3) 

• dashed-dotted (4) 

Predefined Polyline Bundles 

The ESV Workstation supports the following five linetypes: solid, dashed, 
dotted, dot-dashed, and long-dashed. At present, the ESV Workstation 
does not support the following three linetypes: dot-dashed-dot-dotted, 
center, and phantom. 

Text Font and Precision Pairs 

The ESV Workstation supports two distinct text fonts. These two fonts sup- 
port the Stroke precision only. 

Workstation Category and Type 

The ESV Workstation supports workstations of type OUTPUT and OUTINL 
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PHIGS Functions 



In the following list, functions shown in bold are currently supported by the 
ESV Workstation, and functions shown in italics are not currently supported 
by the ESV Workstation. PHIGS PLUS functions are indicated with a "+." 
The FILL AREA 3 WITH DATA function is not supported under the 2.0 server, 
but it is supported if the thin layer is used. 

ADD NAMES TO SET 

ANNOTATION TEXT RELATIVE 

ANNOTATION TEXT RELATIVE 3 

APPLICATION DATA 

ARCHIVE ALL STRUCTURES 

ARCHIVE STRUCTURE NETWORKS 

ARCHIVE STRUCTURES 

AWAIT EVENT 

BUILD TRANSFORMATION MATRIX 

BUILD TRANSFORMATION MATRIX 3 

CELL ARRAY 

CELL ARRAY 3 

CHANGE STRUCTURE IDENTIFIER 

CHANGE STRUCTURE IDENTIFIER AND REFERENCES 

CHANGE STRUCTURE REFERENCES 

CLOSE ARCHIVE FILE 

CLOSE PHIGS 

CLOSE STRUCTURE 

CLOSE WORKSTATION 

COMPOSE MATRIX 

COMPOSE MATRIX 3 

COMPOSE TRANSFORMATION MATRIX 

COMPOSE TRANSFORMATION MATRIX 3 

COMPUTE FILL AREA SET GEOMETRIC NORMAL + 

COPY ALL ELEMENTS FROM STRUCTURE 

DELETE ALL STRUCTURES 

DELETE ALL STRUCTURES FROM ARCHIVE 

DELETE ELEMENT 

DELETE ELEMENT RANGE 
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DELETE ELEMENTS BETWEEN LABELS 

DELETE STRUCTURE 

DELETE STRUCTURE NETWORK 

DELETE STRUCTURE NETWORKS FROM ARCHIVE 

DELETE STRUCTURES FROM ARCHIVE 

ELEMENT SEARCH 

EMERGENCY CLOSE PHIGS 

EMPTY STRUCTURE 

ERROR HANDLING 

ERROR LOGGING 

ESCAPE 

EVALUATE VIEW MAPPING MATRIX 

EVALUATE VIEW MAPPING MATRIX 3 

EVALUATE VIEW ORIENTATION MATRIX 

EVALUATE VIEW ORIENTATION MATRIX 3 

EXECUTE STRUCTURE 

EXTENDED CELL ARRAY 3 + 

FILL AREA 

FILL AREA 3 

FILL AREA 3 WITH DATA + 

FILL AREA SET 

FILL AREA SET 3 

FILL AREA SET 3 WITH DATA + 

FLUSH DEVICE EVENTS 

GENERALIZED DRAWING PRIMITIVE 

GENERALIZED DRAWING PRIMITIVE 3 

GENERALIZED STRUCTURE ELEMENT 

GET CHOICE 

GET ITEM TYPE FROM METAFILE 

GET LOCATOR 

GET LOCATOR 3 

GET PICK 

GET STRING 

GET STROKE 
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GET STROKE 3 

GET VALUATOR 

INCREMENTAL SPATIAL SEARCH 

INCREMENTAL SPATIAL SEARCH 3 

INITIALIZE CHOICE 

INITIALIZE CHOICE 3 

INITIALIZE LOCATOR 

INITIALIZE LOCATOR 3 

INITIALIZE PICK 

INITIALIZE PICK 3 

INITIALIZE STRING 

INITIALIZE STRING 3 

INITIALIZE STROKE 

INITIALIZE STROKE 3 

INITIALIZE VALUATOR 

INITIALIZE VALUATOR 3 

INQUIRE ALL CONFLICTING STRUCTURES 

INQUIRE ANNOTATION FACILITIES 

INQUIRE ARCHIVE FILES 

INQUIRE ARCHIVE STATE VALUE 

INQUIRE CHOICE DEVICE STATE 

INQUIRE CHOICE DEVICE STATE 3 

INQUIRE COLOUR FACILITIES 

INQUIRE COLOUR MAPPING FACILITIES + 

INQUIRE COLOUR MAPPING METHOD FACILITIES + 

INQUIRE COLOUR MAPPING REPRESENTATION + 

INQUIRE COLOUR MAPPING STATE + 

INQUIRE COLOUR MODEL 

INQUIRE COLOUR MODEL FACILITIES 

INQUIRE COLOUR REPRESENTATION 

INQUIRE CONFLICT RESOLUTION 

INQUIRE CONFLICTING STRUCTURES IN NETWORK 

INQUIRE CURRENT ELEMENT CONTENT 

INQUIRE CURRENT ELEMENT TYPE AND SIZE 
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INQUIRE CURVE AND SURFACE FACILITIES + 

INQUIRE DEFAULT CHOICE DEVICE DATA 

INQUIRE DEFAULT CHOICE DEVICE DATA 3 

INQUIRE DEFAULT DISPLAY UPDATE STATE 

INQUIRE DEFAULT LOCATOR DEVICE DATA 

INQUIRE DEFAULT LOCATOR DEVICE DATA 3 

INQUIRE DEFAULT PICK DEVICE DATA 

INQUIRE DEFAULT PICK DEVICE DATA 3 

INQUIRE DEFAULT STRING DEVICE DATA 

INQUIRE DEFAULT STRING DEVICE DATA 3 

INQUIRE DEFAULT STROKE DEVICE DATA 

INQUIRE DEFAULT STROKE DEVICE DATA 3 

INQUIRE DEFAULT VALUATOR DEVICE DATA 

INQUIRE DEFAULT VALUATOR DEVICE DATA 3 

INQUIRE DEPTH CUE FACILITIES + 

INQUIRE DEPTH CUE REPRESENTATION + 

INQUIRE DIRECT COLOUR MODEL FACILITIES + 

INQUIRE DISPLAY SPACE SIZE 

INQUIRE DISPLAY SPACE SIZE 3 

INQUIRE DISPLAY UPDATE STATE 

INQUIRE DYNAMICS OF STRUCTURES 

INQUIRE DYNAMICS OF WORKSTATION ATTRIBUTES 

INQUIRE EDGE FACILITIES 

INQUIRE EDGE REPRESENTATION 

INQUIRE EDIT MODE 

INQUIRE ELEMENT CONTENT 

INQUIRE ELEMENT POINTER 

INQUIRE ELEMENT TYPE AND SIZE 

INQUIRE ERROR HANDLING MODE 

INQUIRE EXTENDED DYNAMICS OF WORKSTATION ATTRIBUTES + 

INQUIRE EXTENDED EDGE REPRESENTATION + 

INQUIRE EXTENDED INTERIOR FACILITIES + 

INQUIRE EXTENDED INTERIOR REPRESENTATION + 

INQUIRE EXTENDED PATTERN REPRESENTATION + 
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INQUIRE EXTENDED POLYLINE FACILITIES + 

INQUIRE EXTENDED POLYLINE REPRESENTATION + 

INQUIRE EXTENDED POLYMARKER REPRESENTATION + 

INQUIRE EXTENDED TEXT REPRESENTATION + 

INQUIRE EXTENDED WORKSTATION STATE TABLE LENGTHS + 

INQUIRE GENERALIZED DRAWING PRIMITIVE 

INQUIRE GENERALIZED DRAWING PRIMITIVE 3 

INQUIRE GENERALIZED STRUCTURE ELEMENT FACILITIES 

INQUIRE HIGHLIGHTING FILTER 

INQUIRE HLHSR FACILITIES 

INQUIRE HLHSR MODE 

INQUIRE INPUT QUEUE OVERFLOW 

INQUIRE INTERIOR FACILITIES 

INQUIRE INTERIOR REPRESENTATION 

INQUIRE INVISIBILITY FILTER 

INQUIRE LIGHT SOURCE FACILITIES + 

INQUIRE LIGHT SOURCE REPRESENTATION + 

INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES 

INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES 3 

INQUIRE LIST OF AVAILABLE GENERALIZED STRUCTURE ELEMENTS 

INQUIRE LIST OF AVAILABLE WORKSTATION TYPES 

INQUIRE LIST OF COLOUR INDICES 

INQUIRE LIST OF COLOUR MAPPING INDICES + 

INQUIRE LIST OF DEPTH CUE INDICES + 

INQUIRE LIST OF EDGE INDICES 

INQUIRE LIST OF INTERIOR INDICES 

INQUIRE LIST OF LIGHT SOURCE INDICES + 

INQUIRE LIST OF PATTERN INDICES 

INQUIRE LIST OF POLYLINE INDICES 

INQUIRE LIST OF POLYMARKER INDICES 

INQUIRE LIST OF TEXT INDICES 

INQUIRE LIST OF VIEW INDICES 

INQUIRE LOCATOR DEVICE STATE 

INQUIRE LOCATOR DEVICE STATE 3 
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INQUIRE MODELLING CLIPPING FACILITIES 

INQUIRE MORE SIMULTANEOUS EVENTS 

INQUIRE NUMBER OF AVAILABLE LOGICAL INPUT DEVICES 

INQUIRE NUMBER OF DISPLAY PRIORITIES SUPPORTED 

INQUIRE OPEN STRUCTURE 

INQUIRE PATHS TO ANCESTORS 

INQUIRE PATHS TO DESCENDANTS 

INQUIRE PATTERN FACILITIES 

INQUIRE PATTERN REPRESENTATION 

INQUIRE PHIGS FACILITIES 

INQUIRE PICK DEVICE STATE 

INQUIRE PICK DEVICE STATE 3 

INQUIRE POLYLINE FACILITIES 

INQUIRE POLYLINE REPRESENTATION 

INQUIRE POLYMARKER FACILITIES 

INQUIRE POLYMARKER REPRESENTATION 

INQUIRE POSTED STRUCTURES 

INQUIRE PREDEFINED COLOUR MAPPING REPRESENTATION + 

INQUIRE PREDEFINED COLOUR REPRESENTATION 

INQUIRE PREDEFINED DEPTH CUE REPRESENTATION + 

INQUIRE PREDEFINED EDGE REPRESENTATION 

INQUIRE PREDEFINED EXTENDED EDGE REPRESENTATION + 

INQUIRE PREDEFINED EXTENDED INTERIOR REPRESENTATION + 

INQUIRE PREDEFINED EXTENDED PATTERN REPRESENTATION + 

INQUIRE PREDEFINED EXTENDED POLYLINE REPRESENTATION + 

INQUIRE PREDEFINED EXTENDED POLYMARKER REPRESENTATION + 

INQUIRE PREDEFINED EXTENDED TEXT REPRESENTATION + 

INQUIRE PREDEFINED INTERIOR REPRESENTATION 

INQUIRE PREDEFINED LIGHT SOURCE REPRESENTATION + 

INQUIRE PREDEFINED PATTERN REPRESENTATION 

INQUIRE PREDEFINED POLYLINE REPRESENTATION 

INQUIRE PREDEFINED POLYMARKER REPRESENTATION 

INQUIRE PREDEFINED TEXT REPRESENTATION 

INQUIRE PREDEFINED VIEW REPRESENTATION 
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INQUIRE RENDERING COLOUR MODEL FACILITIES + 

INQUIRE SET OF OPEN WORKSTATIONS 

INQUIRE SET OF WORKSTATIONS TO WHICH POSTED 

INQUIRE STRING DEVICE STATE 

INQUIRE STRING DEVICE STATE 3 

INQUIRE STROKE DEVICE STATE 

INQUIRE STROKE DEVICE STATE 3 

INQUIRE STRUCTURE IDENTIFIERS 

INQUIRE STRUCTURE STATE VALUE 

INQUIRE STRUCTURE STATUS 

INQUIRE SYSTEM STATE VALUE 

INQUIRE TEXT EXTENT 

INQUIRE TEXT FACILITIES 

INQUIRE TEXT REPRESENTATION 

INQUIRE VALUATOR DEVICE STATE 

INQUIRE VALUATOR DEVICE STATE 3 

INQUIRE VIEW FACILITIES 

INQUIRE VIEW REPRESENTATION 

INQUIRE WORKSTATION CATEGORY 

INQUIRE WORKSTATION CLASSIFICATION 

INQUIRE WORKSTATION CONNECTION AND TYPE 

INQUIRE WORKSTATION STATE TABLE LENGTHS 

INQUIRE WORKSTATION STATE VALUE 

INQUIRE WORKSTATION TRANSFORMATION 

INQUIRE WORKSTATION TRANSFORMATION 3 

INTERPRET ITEM 

LABEL 

MESSAGE 

OFFSET ELEMENT POINTER 

OPEN ARCHIVE FILE 

OPEN PHIGS 

OPEN STRUCTURE 

OPEN WORKSTATION 

NON-UNIFORM B-SPUNE CURVE + 
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NON-UNIFORM B-SPUNE SURFACE + 

POLYLINE 

POLYLINE 3 

POLYLINE SET 3 WITH DATA + 

POLYMARKER 

POLYMARKER 3 

POST STRUCTURE 

QUADRILATERAL MESH 3 WITH DATA + 

READ ITEM FROM METAFILE 

REDRAW ALL STRUCTURES 

REMOVE NAMES FROM SET 

REQUEST CHOICE 

REQUEST LOCATOR 

REQUEST LOCATOR 3 

REQUEST PICK 

REQUEST STRING 

REQUEST STROKE 

REQUEST STROKE 3 

REQUEST VALUATOR 

RESTORE MODELLING CUPPING VOLUME 

RETRIEVE ALL STRUCTURES 

RETRIEVE ANCESTORS OF STRUCTURE 

RETRIEVE DESCENDANTS OF STRUCTURE 

RETRIEVE STRUCTURE IDENTIFIERS 

RETRIEVE STRUCTURE NETWORKS 

RETRIEVE STRUCTURES 

ROTATE 

ROTATE X 

ROTATE Y 

ROTATE Z 

SAMPLE CHOICE 

SAMPLE LOCATOR 

SAMPLE LOCATOR 3 

SAMPLE PICK 
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SAMPLE STRING 

SAMPLE STROKE 

SAMPLE STROKE 3 

SAMPLE VALUATOR 

SCALE 

SCALE 3 

SET ANNOTATION STYLE 

SET ANNOTATION TEXT ALIGNMENT 

SET ANNOTATION TEXT CHARACTER HEIGHT 

SET ANNOTATION TEXT CHARACTER UP VECTOR 

SET ANNOTATION TEXT PATH 

SET AREA PROPERTIES + 

SET BACK AREA PROPERTIES + 

SET BACK INTERIOR COLOUR + 

SET BACK INTERIOR REFLECTANCE EQUATION + 

SET BACK INTERIOR SHADING METHOD + 

SET BACK INTERIOR STYLE + 

SET BACK INTERIOR STYLE INDEX + 

SET BACK PARAMETRIC SURFACE CHARACTERISTICS + 

SET CHARACTER EXPANSION FACTOR 

SET CHARACTER HEIGHT 

SET CHARACTER SPACING 

SET CHARACTER UP VECTOR 

SET CHOICE MODE 

SET COLOUR MAPPING INDEX + 

SET COLOUR MAPPING REPRESENTATION + 

SET COLOUR MODEL 

SET COLOUR REPRESENTATION 

SET CONFLICT RESOLUTION 

SET CURVE APPROXIMATION CRITERIA + 

SET DEPTH CUE INDEX + 

SET DEPTH CUE REPRESENTATION + 

SET DISPLAY UPDATE STATE 

SET EDGE COLOUR + 
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SET EDGE COLOUR INDEX 

SET EDGE FLAG 

SET EDGE INDEX 

SET EDGE REPRESENTATION 

SET EDGETYPE 

SET EDGEWIDTH SCALE FACTOR 

SET EDIT MODE 

SET ELEMENT POINTER 

SET ELEMENT POINTER AT LABEL 

SET ERROR HANDLING MODE 

SET EXTENDED EDGE REPRESENTATION + 

SET EXTENDED INTERIOR REPRESENTATION + 

SET* EXTENDED PATTERN REPRESENTATION + 

SET EXTENDED POLYLINE REPRESENTATION + 

SET EXTENDED POLYMARKER REPRESENTATION + 

SET EXTENDED TEXT REPRESENTATION + 

SET FACE CULLING MODE + 

SET FACE DISTINGUISHING MODE + 

SET GLOBAL TRANSFORMATION 

SET GLOBAL TRANSFORMATION 3 

SET HIGHLIGHTING FILTER 

SET HLHSR IDENTIFIER 

SET HLHSR MODE 

SET INDIVIDUAL ASF 

SET INTERIOR COLOUR + 

SET INTERIOR COLOUR INDEX 

SET INTERIOR INDEX 

SET INTERIOR REFLECTANCE EQUATION + 

SET INTERIOR REPRESENTATION 

SET INTERIOR SHADING METHOD + 

SET INTERIOR STYLE 

SET INTERIOR STYLE INDEX 

SET INVISIBILITY FILTER 

SET LIGHT SOURCE REPRESENTATION + 
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SET LIGHT SOURCE STATE + 

SET LINETYPE 

SET LINEWIDTH SCALE FACTOR 

SET LOCAL TRANSFORMATION 

SET LOCAL TRANSFORMATION 3 

SET LOCATOR MODE 

SET MARKER SIZE SCALE FACTOR 

SET MARKER TYPE 

SET MODELLING CLIPPING INDICATOR 

SET MODELLING CLIPPING VOLUME 

SET MODELLING CLIPPING VOLUMES 

SET OF FILL AREA SET 3 WITH DATA + 

SET PARAMETRIC SURFACE CHARACTERISTICS + 

SET PA TTERN REFERENCE POINT 

SET PATTERN REFERENCE POINT AND VECTORS 

SET PA TTERN REPRESENTA TION 

SET PATTERN SIZE 

SET PICK FILTER 

SET PICK IDENTIFIER 

SET PICK MODE 

SET POLYLINE COLOUR + 

SET POLYLINE COLOUR INDEX 

SET POLYLINE INDEX 

SET POLYLINE REPRESENTATION 

SET POLYLINE SHADING METHOD + 

SET POLYMARKER COLOUR + 

SET POLYMARKER COLOUR INDEX 

SET POLYMARKER INDEX 

SET POLYMARKER REPRESENTATION 

SET RENDERING COLOUR MODEL + 

SET STRING MODE 

SET STROKE MODE 

SET SURFACE APPROXIMATION CRITERIA + 

SET TEXT ALIGNMENT 
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SET TEXT COLOUR + 

SET TEXT COLOUR INDEX 

SET TEXT FONT 

SET TEXT INDEX 

SET TEXT PATH 

SET TEXT PRECISION 

SET TEXT REPRESENTATION 

SET TRIMMING CURVE APPROXIMATION CRITERIA + 

SET VALUATOR MODE 

SET VIEW INDEX 

SET VIEW REPRESENTATION 

SET VIEW REPRESENTATION 3 

SET VIEW TRANSFORMATION INPUT PRIORITY 

SET WORKSTATION VIEWPORT 

SET WORKSTATION VIEWPORT 3 

SET WORKSTATION WINDOW 

SET WORKSTATION WINDOW 3 

TEXT 

TEXT 3 

TRANSFORM POINT 

TRANSFORM POINT 3 

TRANSLATE 

TRANSLATE 3 

TRIANGLE STRIP 3 WITH DATA + 

UNPOST ALL STRUCTURES 

UNPOST STRUCTURE 

UPDATE WORKSTATION 

WRITE ITEM TO METAFILE 
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Compatibility with Prior Releases 

The 2.0 Release is based on the PEX-SI release to the X Consortium and rep- 
resents a major step towards the stability and interoperability of PEX. The 2.0 
Release is based on the 5.0P protocol and the API binding that is the most cur- 
rent and closest to the proposed bindings for PHIGS and PHIGS PLUS. This is 
also the system that multiple major vendors will be using to demonstrate in- 
teroperability during 1991. 

The change to the 5. OP protocol means that programs which run on 
releases prior to the 2.0 Release will not run on the 2.0 Release, and programs 
which run on the 2.0 Release will not run on releases prior to the 2.0 Release. 
The protocols are not compatible. For X-only programs there is no protocol 
change, and they will work on any release. 

The 2.0 Release maintains compatibility with the API binding (function 
calls) to PHIGS and PHIGS PLUS. With the exception of pgse, pgdp and 
pescape, no change is required. The 2.0 Release provides a thin layer 
binding which translates the old C-binding calls (now referred to as the 1.3 
binding) to the new C-binding calls. There has been no change in the 
FORTRAN binding, and for these applications you need only to recompile and 
link. 

• The location of the include files changes slighdy in the 2.0 Release. 
This change was made by the X Consortium. The include files for the 
new PHIGS binding are located in the following directory: 

/usr/include/X11/phigs 

• The include files for the old PHIGS binding are located in the follow- 
ing directory: 

/usr/include/X1 1 /phigsl .3 

• To compile your old code you must change the following in your ap- 
plication: 

#include <X1 1/extensions/phigs.h> 

to 

#include <X11 /phigsl .3/phigs.h> 

• If you use a compile line option to specify include paths, then add the 
following to your compile line or Makefile: 

-l/usr/include/X1 1 /phigsl .3 

• To compile for the new binding, put the following in your source 
code: 

#include <X11/phigs/phigs.h> 
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Alternately, you can put the following in your source code: 

#include <phigs.h> 

and add the following to your compile line: 

-l/usr/include/X11/phlgs 

• Similar changes need to be made to paths to locate phigs77.h for 
FORTRAN programs. phlgs77.h has moved from 
/usr/include/X11 /extensions to /usr/include/X11/phigs. 

The other change in the 2.0 Release is in the libraries which are available,, 
When using the 1.3 binding, you must link in libPEXaph.3.a prior to 
HbPEXapi.a. The graphics libraries on the ESV Workstation are: 

HbMrm.a Motif resource manager library 

HbPEX77.a PHIGS FORTRAN library 

HbPEXapLa PHIGS latest C library 

libPEXaph .3,a PHIGS 1.3 binding C library 

libPEXt-a E&S PHIGS toolkit library 

libUil.a Motif UIL library 

libX1 1 .a X graphics library 

HbXEandSexta E&S X extension library I 

NbXau.a X authorization library 

HbXaw.a X Athena widget library 

libXdmcp.a X display manager communications protocol 

libXext.a X extension library 

libXinputa X input extension library 

UbXm.a Motif widget library 

libXmu.a X widget utilities library 

libXpick.a E&S X pick extension library 

llbXt.a X Toolkit library 

liboldX.a X old compatibility library 
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OPEN XPHIGS 
Name 

OPEN XPHIGS - open and initialize PHIGS in the X environment. 
Syntax 

void 

popenjcphlgs (error_file,memory,xlnfo_mask,xinfo) 

char *errorJile; 

Plong memory; Co<£rfcA«o Syntax 

unsigned long xinfo_mask; )Kl zo fc eiXASC ^^ 

Pxphlgs Info *xlnfo; 

Required PHIGS Operating States ' ~ 

rOrP\\ C. *■- - / 
(PHCL,WSCL,STCL,ARCL) 

Description 

OPEN XPHIGS is similar to OPEN PHIGS but allows specification of addi- 
tional run-time options. It initializes the API and enables access to the PHIGS 
functions. OPEN PHIGS or OPEN XPHIGS must be called prior to calling 
any other PHIGS functions. 

Input Parameters 

errorjfile A pointer to the error file in which to log PHIGS error messag- 
es. The error file can be either a pointer to a valid UNIX file 
name or a null pointer, for example (char*)0. A null pointer 
implies that standard error is to be used as the error file. If a 
file name is specified, PHIGS will attempt to access the file for 
writing. If this attempt fails, OPEN XPHIGS will fail and the 
appropriate error will be reported to standard error. 

The error file argument passed to OPEN XPHIGS will be 
passed to ERROR HANDLING. ERROR HANDLING will also 
pass this argument to ERROR LOGGING. If for some reason, 
ERROR LOGGING cannot access the specified file, the error 
message will be written to standard error. ERROR LOGGING 
appends messages to the error file; it does not truncate the file 
when OPEN XPHIGS is called. If the specified file does not 
exist, it will only be created if ERROR LOGGING is called. 

ERROR LOGGING writes the abstract PHIGS function name, 
the error number, and an error description to the error file. If 
for some reason the text for the function name and/or error de- 
scription can't be determined, ERROR LOGGING will just 
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write the function number and the error number. 

memory Not used by the PEX-SI API. 

xinfo mask A bitmask indicating which of the options are being set. This 
mask is a bitwise OR of one or more of the valid option mask 
bits and indicates which fields of the Pxphigsjnfo structure 
are set. 

PXPHIGS JNFO ^DISPLAY The display pointer: display 

PXPHIGSJNFO J=IMDB The resource manager: rmdfo 

PXPHIGS_APPLJD The application name and class: appljd 

PXPHIGSJNFO_ARGS The command line arguments: args 

PXPHIGS JNFO J=LAGS_NO_MON 

The No Monitor flag: flags.no_monitor 

PSPHIGSJNFO_FLAGS_CLIENT_SS 

The Force Client SS flag: flagsJorce_cllent_SS 

xinfo A pointer to a Pxphigsjnfo structure. This structure is used 

to specify X-related options to PHIGS. xinfo is defined in 
phigs.h as follows: 

typedef struct { 



c 



Display 


* display; /* valid display pointer */ 


XrmDatabase 


rmdh; /* a valid database */ 


struct { 




char 


*name; 


char 


class; 


} appljd; 


/* for resolving database attributes */ 


struct { 




int 


*argc_pi 


char 


**argv, 


} args; 


/* for merging args into specified database */ 


struct { 




unsigned 


no_monitor: 1 ; 



( 



/* l ==> monitor will not be executed */ 
unsigned forcejclientJSS\ 

/* l ==> always use client-side CSS */ 
Jflags; 
} Pxphigsjnfo; 

Only the fields indicated by xlnfojmask are examined. 
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display Specifies both the PHIGS default server and the connection 
PHIGS is to use when communicating with it. The PHIGS de- 
fault server holds the master copy of the central structure 
store, and is where tool workstations are opened if their loca- 
tion is not specified to the OPEN WORKSTATION function. 
PHIGS uses the specified connection for all communication to 
the default server, even if a different connection is specified 
for a drawable workstation in a subsequent call to OPEN 
WORKSTATION. PHIGS uses the specified connection for the 
duration of the PHIGS session; it must not be closed before 
calling CLOSE PHIGS. If display is not specified, the default 
server will be the one returned by a call to XDisplay Name() 
with an argument of NULL. 

rmdb An X resource database handle. PHIGS uses this database to 
build the default workstation description tables. Database 
searches are on the resource names and classes listed below. 
Each search is qualified by the name and class specified in 
appljd. If arguments are also specified, PHIGS will merge 
them into the database prior to searching the database for 
resources PHIGS recognizes. Any merged arguments will be 
removed from the argument list. The resources PHIGS 
recognizes are 



Argument String 


Resource Name 


Resource Class 


Type Valid Values 


•display 


display 


Display 


String 


-bufmode 


bufMode 


BufMode 


String single 1 double 


= 


geometry 


Geometry 


String 


•label 


label 


Label 


String 


-iconlabel 


IconLabel 


IconLabel 


String 



The display resource specifies the name of the default server. The 
bufMode resource specifies the default buffering mode, "single" or 
"double." Single buffering is not available on the ES V. The geometry 
resource specifies the default window location and size for 
phigs_ws_type_x_tool workstation types. The geometry is specified 
in the standard X geometry format: 

<width>x<height> { +- } <xof f set> { +- } <yof f set> 
The label resource specifies the window label for 
phigs_ws_type_x_tool workstation types. The IconLabel resource 
specifies the icon label for phigs_ws_type_x_tool workstation types. 
appljd. name and appljd.class are the application name and class to use 
when resolving resource database attributes. If not specified, the name phlgs 
and class Phigs are used. 
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args.argc_p 

A pointer to the argument count. 

args.arg vThe array of command line arguments. The arguments are 
searched for attributes recognized by PHIGS and are merged 
into the specified database, if any. 

flags.nojmonltor 

Indicates whether the PHIGS Monitor (PM) is executed during 
popen__phigs(). The PM is a separate program started by 
PHIGS that handles window events and PHIGS input for 
PHIGS workstations. PHIGS has complete control over this 
program; no user action is required to deal with it other than to 
indicate if it should be used or not. If the PM is not executed 
(f lags.no jmonitor^ 1 ), PHIGS will not monitor and respond 
to X window events nor will it provide any PHIGS worksta- 
tions that support PHIGS input devices. PHIGS workstations 
that support PHIGS input devices. All the predefined worksta- 
tion types will be of category OUTPUT (output only). If the 
PM is executed (flags.no_monitor = 0), PHIGS will monitor 
relevant window events and will provide predefined worksta- 
tion types of category OUTIN (input and output). 

flags.force_cttent_SS 

Indicates whether the API should use client side structure stor- 
age even if server side structure storage is available in X serv- 
ers with the PEX extension. flags.force_client_SS = 1 indi- 
cates that client side structure storage should always be used. 
flagsJorce_client_SS = indicates that server side structure 
storage should be used if available. Client side structure stor- 
age is not available on the ES V. 

Execution 

OPEN XPHIGS sets internal state information and then calls popen_phigs(). 



C 
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OPEN PEX 

Name 

OPEN PEX - open and initialize the PEX environment -1.3 compatibility only 

Syntax 

void 

popenpex(error_fite,memory,xinfo) 
Pchar *error_file; 

slzejt memory, 

Po pen pex Info *x!nfo; 

Required PHIGS Operating States 

(PHCL,WSCL,STCL,ARCL) 

Description 

OPEN PEX is similar to OPEN PHIGS. It initializes the API and enables ac- 
cess to the PHIGS functions. It also allows specification of run-time options 
and the merging of resource manager database (RMDB) attributes which 
OPEN PHIGS does not allow. OPEN PHIGS or OPEN PEX must be called 
prior to calling any other PHIGS functions. 

Input Parameters 

errorjfile A pointer to the error file where PEX error messages are 

logged. The error file can be either a pointer to a valid UNIX 
file name or a null pointer {e.g., (Pchar*)0). A null pointer im- 
plies that standard error is to be used as the error file. If a file 
name is specified, PEX will attempt to access the file for writ- 
ing. If this attempt fails, OPEN PEX will fail and the appropri- 
ate error will be reported to standard error. 

The error J\le argument passed to OPEN PEX will be passed 
to ERROR HANDLING. ERROR HANDLING will also pass 
this argument to ERROR LOGGING. If for some reason 
ERROR LOGGING cannot access the specified error file, the 
error message will be written to standard error. 
ERROR LOGGING appends messages to the error file, and it 
does not truncate the file when OPEN PEX is called. If the 
specified file does not exist, it will only be created if 
ERROR LOGGING is called. 

ERROR LOGGING writes the PHIGS or PHIGS PLUS function 
name, the error number, and an error description to the error 
file. If for some reason the text for the function name and/or 
error description cannot be determined, ERROR LOGGING 

will just write the function number and the error number. 
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memory Ignored by the API. 

xinfo A pointer to a Popenpexinfo structure. This structure is used 

to specify X-related options to PHIGS. xinfo is defined in 
phigs.h as follows: 

typedef struct { 

'display, 

rdb; 

*name; 

*classname\ 

*argc_p; 



Display 

DisXrmDatabase 

char 

char 

int 

char 

struct { 

unsigned 

unsigned 
} flags; 
} Popenpexinfo; 

Popenpexinfo Parameters 

Note: All fields must be set to a valid value or NULL. 



**argv\ 

no_moniton 1 ; 
force_client_SS; 



display 



rdb 



name 



classname 

argcjp 
argv 



The display pointer for the server connection to use, rather 
than creating a connection to the default server. It must be ei- 
ther NULL or a valid display pointer. If a valid display pointer 
is specified, then the API will use it as the start-up server. If 
display is NULL, the API will attempt to connect to the default 
server. 

An X resource database handle. PHIGS uses this database to 
build the default workstation description tables. 

The application name to use when resolving resource database 
attributes. If not specified, the name phigs is used. 

The class to use when resolving resource database attributes. 
If not specified, the class Phigs is used. 



A pointer to the argument count. 

The array of command line arguments. The argument is 
searched for attributes recognized by PHIGS, and they are 
merged into the specified database, if any. 

flags no monitor 

Should be set to 1 if X is going to be used for input, or to if 
PHIGS input is used. 

flags.force_client_SS 

Should be set to 0. 



( 



C 



( 
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Execution 

OPEN PEX fills in a 2.0 Pxphlgsjnfo structure with values from the 
Popenpexinfo structure. It then calls popenxphigs. Previously the rdh, 
name, classname, argcjp, argv, and flags Jorce_client_SS fields were 
ignored. With the 2.0 release, these fields must be either used or initialized to 
the default values below. 

When popenphlgsQ is used to initialize the API it behaves as though the 
following values were assigned to the fields of Popenpexinfo: 

'display = NULL 

rdb = NULL 



*name 


= 


NULL 


*classname 


= 


NULL 


*argc_p 


= 


NULL 


**argv 


= 


NULL 


flags.no_monitor 


= 





flagsJorce_client_SS= 
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OPEN WORKSTATION 

Name 

OPEN WORKSTATION - create a PHIGS workstation 

Syntax 

void 

popen_y/B(wBjd,connJd,wsjype) CcxcTOam SyMV^y. iM 

Pint wsjd; 1-0 *.zue*&E Mcrre^ 

char *connJct 9 

Pint ws_Jype\ 

Required PHIGS Operating States 

(PHOP,*,*,*) 

Description 

OPEN WORKSTATION opens a workstation of the specified workstation 
type. The workstation state list is created and initialized to conform as nearly 
as possible to the workstation description table associated with the specified 
workstation type. If the workstation is successfully opened, the PHIGS work- 
station state variable is set to WSOP. 

PEX-SI supports two predefined workstation types, x_tool and 
x_drawable. Their characteristics are described below. In addition, the 
application can create and modify its own workstation types with the 
WORKSTATION TYPE CREATE and S-2 WORKSTATION TYPE SET 

functions. 

If the workstation is opened successfully, a specific workstation type is 
created and associated with the open workstation. This specific workstation 
type contains the workstation description table that describes the capabilities 
of the opened workstation. The specific workstation type can be retrieved 
with INQUIRE WORKSTATION CONNECTION AND TYPE. 

Input Parameters 

wsjld The workstation identifier to be associated with this worksta- 

tion. This value is used to identify the workstation in subse- 
quent PHIGS function calls. 

connjd A pointer to the connection identifier of the workstation. The 
type of value to use depends on the workstation type. 
x_tool If the conn_Jd is NULL, a window is created on the 
default server. If the connjidis not NULL, it is inter- 
preted as a display name. A window for the worksta- 
tion is created on the named server, provided that 
server supports the X extension. An example of using 
this would be 
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Popen_ws (ws_id, (char*) "unix: 0", phigs_ws_type_x_tool) ; 

x_drawable 

The connection identifier must be a pointer to a 
Pconnid_x_drawable structure, cast to a char*. 
Pconnid_x__drawable is defined in phigs.h. 

ws_type The type of workstation to open. Recognized types are de- 
scribed fully in the "Available Workstation Types" section be- 
low. They are declared in phigs.h. A short summary is listed 
here. 

phigs_ws_type_x_tool 

PHIGS creates an X window for the workstation on a specified 
or default server. 

phigs_ws_type_x_drawable 

PHIGS uses a specified X window for the workstation. 

Execution 

OPEN WORKSTATION opens a PHIGS workstation of the specified type and 
associates it with the specified workstation identifier. 

When a workstation is opened, PHIGS creates a copy of the workstation 
type specified in the OPEN WORKSTATION call and binds it to the opened 
workstation. This copy is called the specific workstation type. The 
workstation description table (WDT) of this specific type is checked against 
the capabilities of the server and window PHIGS is using for the workstation. 
If the capabilities specified by the WDT cannot be realized with that server 
and window, PHIGS modifies the WDT of the specified workstation type to 
reflect the available capabilities. The workstation type parameter to OPEN 
WORKSTATION is not modified; only the specific workstation type is 
(potentially) modified. The specific workstation type bound to a workstation 
can be retrieved with the PHIGS function INQUIRE WORKSTATION 
CONNECTION AND TYPE. 

Some of a workstation type's workstation description table values can be 
changed by the application prior to opening a workstation of that type. See 
WORKSTATION TYPE CREATE and WORKSTATION TYPE SET for more 
information on this. 

Available Workstation Types 

phlgs_ws_type_x_tool 

PHIGS creates an X window on a specified or default server and uses it for the 
PHIGS workstation's display surface. If the PHIGS Monitor is running (see 
OPEN PHIGS), the default category of this workstation type is OUTIN, which 
indicates that both input and output are available; otherwise the default cate- 
gory is OUTPUT 



ESV Workstation Reference Manual [2.0] 1 - 37 



ES/PEX 



If the category is OUTIN, PHIGS creates an additional input-only window 
that it uses to detect pointer events for input devices. This window is 
transparent, overlies the output window completely, and duplicates any size 
and position changes made to the output window. 

Many of the characteristics of an x_tool workstation type, such as its size 
and position, can be set prior to opening the workstation. See the 
WORKSTATION TYPE CREATE and WORKSTATION TYPE SET manual 
pages for a complete list of the modifiable characteristics and their default 
settings. 

phigs_ws__type_jc_drawable 

PHIGS uses an application-specified X window the for PHIGS 
workstation's display source. The window to use is specified in the 
connection identifier parameter. The window must be open and associated 
with a server that supports the PEX extension. 

If the PHIGS Monitor is running (see OPEN PHIGS), the default category 
of this workstation type is OUTIN, which indicates that both input and output 
are available; otherwise, the default category is OUTPUT. 

Some of the characteristics of an x_tool drawable workstation type, such 
as its size and position, can be set prior to opening the workstation. See 
WORKSTATION TYPE CREATE and WORKSTATION TYPE SET man 
pages for a complete list of the modifiable characteristics and their default 
settings. 

Window System Interaction 

Workstation DC limits correspond to the window size used by the PHIGS 
workstation when it is opened. The units are drawable coordinates. When the 
API responds to a window resize event, more or less of the window will be 
exposed; the PHIGS output will not be scaled. Decreases in size cause portions 
of the PHIGS output to be clipped away if the new size is less than the PHIGS 
viewport limits. Size increase beyond the viewport limits will not reveal any 
additional PHIGS output. 

PHIGS automatically redraws the PHIGS workstation when portions of it 
are exposed, such as when it is brought to the top of other windows or moved 
from an iconic state to an open state. This redrawing may potentially change 
portions of the workstation state list by making the state of visual 
representation correct and making all requested entries current. 

For both tool and drawable workstations, a DestroyNotlfy event on the 
workstation's window will likely cause PHIGS to exit. A DestroyNotlfy 
event is generated either by the application or more likely by the operator 
when he destroys or "Quits" the window. 



( 



C 
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GENERALIZED DRAWING PRIMITIVE 

Name 

GENERALIZED DRAWING PRIMITIVE (GDP) - create 2D GDP elements 

(none available on ES V Workstations) 

Syntax 

void 

pgdp ( polntjist, gdpjd, gdpjdata ) 

Ppointjist "polntjist, array of points 

Pint gdpjd; GDP function identifier 

Pgdp_data *gdp_data; data record pointer 

Required PHTGS Operating States 

(PHOP, *, STOP, *) 

Input Parameters 

point list A pointer to a structure containing a list of x and y values in 
Modelling Coordinates (MC). Ppoint Jist is defined in 
phigs.h as: 

typedef struct { 

Pint num_points; /* number of Ppoints in the list */ 
Ppoint *points\ /* list of points */ 

} Ppointjist; 

Ppoint is defined in phigs.h as: 

typedef struct { 

Pf loat x; /*x coordinate */ 

Pf loat y, /*y coordinate */ 

} Ppoint; 

pointjist is ignored for ESV Series Workstations. 

gdp_id An integer specifying the GDP to be performed. 

gdpjdata A pointer to a Pgdp_data union containing the information 
needed to perform the function specified by gdpjd. 
Pgdp_data is defined in phigs.h as: 

typedef union { 

struct { 

Pint unused; 
}gdp_r1; 

Pdata unsupp; /* unsupported GDP data record*/ 
/* implementation dependent */ 
} Pgdp_data; 
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The unsupp field in the Pgse_data structure is of type Pdata which is de- | 

fined in phigs.h: V_. 

typedef struct { 

size_t size; /* size of data */ 

char *data\ /* pointer to individual GDP data */ 

} Pdata; 

Description 

GDP creates an implementation-dependent drawing primitive. On the ESV 
Series Workstations there are no 2D drawing primitives available. 

Execution 

If the current edit mode is insert, the structure element created by the GDP 
function is inserted into the open structure after the element pointed to by the 
element pointer. If the current edit mode is replace, the GDP element replaces 
the element pointed to by the element pointer. In either case, the element 
pointer is updated to point to the new structure element. 

Support for GDPs is implementation- and workstation-dependent. On the 
ESV Series Workstations there are no 2D drawing primitives available. 

Errors 

Ignoring function, function requires state (PHOP, *, STOP, *) 



( 



c 
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GENERALIZED DRAWING PRIMITIVE 3 

Name 

GENERALIZED DRAWING PRIMITIVE 3 (GDP3) - create 3D GDP elements 

Syntax 

void 

pgdp3 ( pointjist, gdp3_id, gdp_data ) 



array of points 

GDP function identifier 

data record pointer 



Ppoint_llst3 *point_iist, 
Pint Qdp3Jd; 

Pgdp_data3 *gdp_data; 

Required PHIGS Operating States 

(PHOP, *, STOP, *) 

Input Parameters 

point_list A pointer to a structure containing a list of x and y values in 
Modelling Coordinates (MC). 

Ppoint Jist3 is defined in phigs.h as: 
typedef struct { 

num_points m , /* number of Ppoints in the list*/ 
'points; /* list of points */ 



Pint 
Ppoint3 
} Ppoint_list3; 

where: 



num_points 



points 



Number of points passed in the points 
parameter. This is ignored for ES V Series 
Workstations. 



A pointer to a list num_points long of 
Ppoint structures containing x and y values 
in Modelling Coordinates (MC).This is 
ignored for ESV Series Workstations. 

Ppoint3 is defined in phigs.h as: 

typedef struct { 

Pf loat x; /* x coordinate*/ 

Pf loat y, /* y coordinate */ 

Pf loat r, /* z coordinate */ 

} Ppoint3 ; 
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gdp3_Jd An integer specifying the GDP to be performed. The follow- £ 

ing GDPs are defined for the ESV workstation: V_ 

PES_GDP_SPHERE 

PES_GDP_SPHEREJRADIUS 

PESJ5DP__SPHERE_COLR 

PESJ5DP_SPHEREJRADIUS_COLR 

PES_GDP_CYLINDER 

PES_GDP_CYLINDER_RADIUS 

PESJ5DP_CYLINDER_COLR 

PESJ5DP_CYLINDER_RADIUS_COLR 

gdpjdata A pointer to a Pgdp_data union containing the information 
needed to perform the function specified by gdp3_id. 

Pgdp_ data is defined in phigs.h as: 

typedef union { 

struct { 

Pint unused; 

}gdp_j1; 

Pdata unsupp; /* unsupported GDP data record */ 
/* implementation dependent */ 
} Pgdp_data; 

The unsupp field in the Pgsejfata structure is of type Pdata which is 
defined in phigs.h: 

typedef struct { 

size_t size; /* size of data */ 

char *data; /* pointer to individual GDP data */ 

} Pdata; 



( 



( 
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Description 

GDP creates an implementation-dependent drawing primitive. On the ESV 
Series Workstations the following GDPs are available: 

Spheres with inherited colour and radius. 
(PES_GDP_SPHERE) 

Spheres with specified radius and inherited colour. 
(PES_GDP_SPHERE_RADIUS) 

Spheres with specified colour and inherited radius. 
(PES_GDP_SPHERE_COLR) 

Spheres with specified radius and colour. 
(PES_GDP_SPHERE_RADIUS_COLR) 

Cylinders with inherited colour and radius. 
(PES_GDP_CYLINDER) 

Cylinders with specified radius and inherited colour. 
(PES_GDP_CYLINDER_RADIUS) 

Cylinders with specified colour and inherited radius. 
(PES__GDP_CYLINDER_COLR) 

Cylinders with specified colour and radius. 
(PES_GDP_CYLINDER_RADIUS_COLR) 

Execution 

If the current edit mode is insert, the structure element created by the GDP 
function is inserted into the open structure after the element pointed to by the 
element pointer. If the current edit mode is replace, the GDP element replaces 
the element pointed to by the element pointer. In either case, the element 
pointer is updated to point to the new structure element. 

Support for GDPs is implementation- and workstation-dependent. 

Individual GDPs 

For convenience, each individual GDP is provided its own defined structures 
to hold data unique to it. These structures should be pointed at by the data 
field in the Pdata structure described above. Following is a description of 
each GDP and its associated data types and definitions. All of these structures 
are defined in esgdp.h. 
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List of Spheres 

Multiple spheres may be specified in a single gdp3 call. All sphere elements 
are characterized by a list of 3D center points that define sphere centers. 
Spheres have attributes of radius, colour, and precision. All spheres are 
drawn as surfaces. Sphere precision is an attribute established by a GSE el- 
ement that defines how accurately spheres are drawn. Spheres that are drawn 
with lower precision values are drawn faster but look less like spheres than 
spheres drawn with higher precision values. 

There are four forms of the Spheres element. The most simple form holds 
only a list of center points of spheres. A second form holds a center and a 
radius for each sphere. A third form holds a center and a colour for each 
sphere. The fourth form contains both a center, a colour and a radius for each 
sphere. The four different forms of the sphere element all start with a common 
header structure, defined as follows: 

typedef struct { 

Pint coir_modei; /* colour model */ 

Pint count; /* number of sphere definitions */ 

/* List of sphere structures */ 

} Psphere_data; 



c 



( 



c 
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Simple List of Spheres 

The Simple List of Spheres element has only center point data. The sphere co- 
lour comes from the current surface colour attribute. The sphere radius is tak- 
en from the Sphere Radius Attribute that is established by a GSE node (see 
the function pgse). The structure supporting the Simple List of Spheres ele- 
ment is: 

/* Simple Spheres */ 

typedef struct _Psphere_simple_ { 

Psphere data head; 

Psphere data[1]; /* Variable length array of centers */ 

} Psphere_simple; 

Note that the data field in the above structure is defined with only 1 array 
element, but it is actually used as a variable length array. (This is the only way 
to name structure fields of variable length arrays in the C language.) The field 
is provided for the convenience of application programmers who prefer to 
access their data by array element name rather than by doing pointer 
arithmetic on a pointer variable. 

A macro is also provided to determine the amount of memory needed for 
a Psphere_simple structure that holds n sphere center points: 

/* Macro to calculate size of Simple Spheres structure */ 
/* n is the number of spheres defined in the list */ 
#define sz_Psphere_simple(n) 
((n-1) * sizeof (Psphere) + sizeof(Psphere_simple)); 
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List of Spheres With Radius | 

The List of Spheres With Radius element has center point data and sphere ra- 
dii. The sphere colour comes from the current surface colour attribute. The 
sphere precision is taken from the Sphere Precision Attribute that is estab- 
lished by a GSE node (see the function pgse). The structure supporting the 
List of Spheres With Radius element is: 

/* Spheres with radii */ 
typedef struct { 

PpointS center, /* center of sphere */ 

Pf loat radius; /* radius of sphere */ 

} Psphere__radius; 
typedef struct _Psphere_w_radius_ { 

Psphere_data head; 

Psphere__radius data[1]; /* Variable length array of centers and radii */ 
} Psphere_w_radius; 

/* Macro to calculate size of Spheres With Radius structure */ 
/* n is the number of spheres defined in the list */ 
#define sz_Psphere_w_radius(/i) 
((#>-1)*sizeof(Psphere_jadIus) + sizeof(Psphere_w__radius)); 



( 



c 
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List of Spheres With Colour 

The List of Spheres With Colour element has center point data and sphere co- 
lours. The sphere radius comes from the current sphere radius attribute. The 
sphere precision is taken from the Sphere Precision Attribute that is estab- 
lished by a GSE node (see the function pgse). The structure supporting the 
List of Spheres With Colour element is: 

/* Spheres with colour */ 
typedef struct { 

PpointS center, /* center of sphere */ 

Pcoval coir, /* colour of sphere */ 

} Psphere_colr; 
typedef struct _Psphere_w_colr_ { 

Psphere_data head; 

Psphere_colr data[1]; /* Variable length array of centers and colour*/ 
} Psphere_w_colr; 

/* Macro to calculate size of Spheres With Colour structure */ 
V* n is the number of spheres defined in the list */ 
#define sz_Psphere_w_colr(n) 
((n-1)*sizeof(Psphere_colr) + sizeof(Psphere_data)); 
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List of Spheres With Radius and Colour 

The List of Spheres With Radius and Colour element has center point data, 
sphere radii and sphere colours. Each sphere radius and sphere colour comes 
from data within the element. The sphere precision is taken from the Sphere 
Precision Attribute that is established by a GSE node (see the function pgse),, 
The structure supporting the List of Spheres With Radius and Colour element 
is: 

/* Spheres with radius and colour. */ 
typedef struct { 

PpointS center, /* center of sphere */ 

Pf loat radius; /* radius of sphere */ 

Pcoval coir, /* colour of sphere */ 

} Psphere_radius_colr; 
typedef struct _Psphere_w_radius_colr_ { 

Psphere__data head; 

Psphere_radius_colr data[1]; /* Variable length array of centers, 

radii, coir */ 
} Psphere__w_radius_colr; 

/* Macro to calculate size of Spheres With Radius and Colour structure */ 
/* n is the number of spheres defined in the list */ 

#define szJPsphere_w_radlus_colr(n) | 

((/M)*sizeof(Psphere_radius_coIr) + sizeof(Psphere__w_radius_colr)); V 



c 
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Cylinders 

Multiple cylinders may be specified in a single gdp3 call. Cylinder GDPs are 
defined as "list of cylinder" lists. A single list of cylinders is defined much 
like a polyline. The cylinders in the list are connected end to end by a common 
center point on their end caps. Each cylinder GSE element can have multiple 
lists of cylinders within it. 

Like spheres, cylinders can be defined very simply by specifying only the 
centers of their capping circles, taking their radius and co/oi/r attributes from 
attribute elements previously defined in the structure. Or, they can include 
within their definition their colour, or radius, or both. Cylinders have 
attributes of radius, colour, and precision. All cylinders are drawn as 
surfaces. 

Cylinder precision is an attribute established by a GSE element that 
defines how accurately cylinders are drawn. Cylinders that are drawn with 
lower precision values are drawn faster but look less like cylinders than 
cylinders drawn with higher precision values. 

There are four forms of the Cylinders GDP element. The most simple 
form holds only a list of center points of cylinder end or capping circles. A 
second form holds a center and a radius for each cylinder end. A third form 
holds a center and a colour for each cylinder. The fourth form contains both 
a center, a colour and a radius for each cylinder. The data defining the 
cylinder element must reside in contiguous memory. The four different forms 
of the cylinder element all start with a common header structure, defined as 
follows: 

typedef struct { 

Pint colr_modei", /* colour model */ 

Pint numjists; /* number of lists of cylinders */ 

/* List of cylinder lists */ 

} Pcyl_Nst_data; 

typedef struct { 

Pint num_cyi_ends; /* number of cylinder end points */ 

/* List of cylinder structures */ 
} Pcyljlst; 

typedef struct { 

Ppoint3 center, /* center of cylinder */ 

} Pcylinder; 
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Simple Cylinders 

The most simple Cylinder element contains only 3D end points. The cylinder 
colour comes from the current surface colour attribute. The cylinder radius is 
inherited from the Cylinder Radius Attribute that is established by a GSE 
node (see the function pgse). Each list within the simple list of cylinder lists 
has the following structure: 

typedef struct _PcylJ ist_simple_ { 

Pcyljist head; 

Pcylinder data[1]; /*listofendpoints */ 
} Pcyljlstjslmple; 

The complete data necessary to create a simple Cylinder element consists 
of the Cylinder header structure Pcyl Jlst_data described above followed by 
the desired number of Pcyljist_simple structures. 

The size of any given list with n cylinders within the list of lists of a 
simple Cylinder element can be determined with the following macro where 
n is the number of cylinders defined in the list: 

#define sz_PcyLHst_simple(n) (slzeof(PcyUist__simple) + (n-1) * 
sizeof(Pcylinder)) 



c 



c 



c 
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Cylinders With Radius 

The Cylinder With Radius element can contain a radius along with 3D end 
points. The cylinder colour comes from the current surface colour attribute. 
The cylinder precision is taken from the Cylinder Precision Attribute that is 
established by a GSE node (see the function pgse). A pointer to a cylinder 
list within the list of cylinder lists can be cast as the following type: 

typedef struct _Pcy!Jist_radius_ { 

PcylJIst head; 

Pcylinderradius data[1]; /* list of endpoints and radii */ 
} Pcyljist_radius; 
where the structure Pcylinder_radius is defined as: 

typedef struct { 

Ppoint3 center, /* center of cylinder */ 

Pf loat radius; /* radius of cylinder */ 

} Pcylinderradius; 

The complete data necessary to create a Cylinder With Radius element 
consists of the Cylinder header structure Pcyl Jist_data described above 
followed by the desired number of Pcyl_list_jadius structures. 

The size of any given list within the list of lists of a Cylinder With Radius 
element can be determined with the following macro: 

#define sz_Pcyl_list__radius(/i) 

(sizeof(Pcyl_list__radius) + (n-1) * sizeof(Pcylinder_radius)) 
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Cylinders With Colour 

The Cylinder With Colour element can contain a Colour along with 3D end 
points. The cylinder radius is inherited from the Cylinder Radius Attribute es- 
tablished by a GSE element. The cylinder precision is taken from the Cylin- 
der Precision Attribute that is established by a GSE element (see the function 
pgse). A pointer to a cylinder list within the list of cylinder lists can be cast 
as the following type: 

typedef struct _PcylJist_Colr_ { 

Pcyljist head; /*# of points in the cylinder */ 

PcyIinder_coIr data[1J; /* list of endpoints and colours */ 

} PcyI_iist_colr; 

where the structure Pcyllnder_colr is defined as: 

typedef struct { 

Ppoint3 center, /* center of cylinder */ 

Pcoval coir, /* colour of cylinder */ 

} PcyIinder_colr; 

The complete data necessary to create a Cylinder With Colour element 
consists of the Cylinder header structure Pcyl_list_data described above 
followed by the desired number of PcylJist__colr structures. 

The size of any given list within the list of lists of a Cylinder With Colour f 

element can be determined with the following macro, where n is the number I 

of cylinders defined in the list: 

#define sz_Pcyl_Hst_colr(n) 

(sizeof(PcylJist_colr) + (/M) * slzeof(Pcylinder_colr)) 



c 
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Cylinders With Radius and Colour 

The Cylinder With Radius and Colour element can contain a radius and co- 
lour along with 3D end points. The cylinder precision is taken from the Cyl- 
inder Precision Attribute that is established by a GSE element (see the 
function pgse). A pointer to a cylinder list within the list of cylinder lists can 
be cast as the following type: 

fypedef struct _PcyMlst_radius_Colr_ { 

Pcyl Jist head; /* # of points in the cylinder */ 

Pcylinderj , adius_colr data[1]; /* list of cyl data */ 

} PcylJist_radius_colr; 

where the structure Pcylinder_radius_colr is defined as: 

typedef struct { 

Ppoint3 center, /* center of cylinder */ 

Pf loat radius; /* radius of cylinder */ 

Pcoval coir, /* colour of cylinder */ 

} Pcylinder_radius_colr; 

The complete data necessary to create a Cylinder With Radius and Colour 
element consists of the Cylinder header structure Pcyl JistjJata described 
above followed by the desired number of PcyHist__radius_coir structures. 

The size of any given list within the list of lists of a Cylinder With Radius 
and Colour element can be determined with the following macro, where n is 
the number of cylinders defined in the list: 

#define sz__Pcyl_list_radius_colr(n) 

(sizeof(PcyMist_radius_coIr) + (#Kl) * sizeof(Pcyiinderjadius_colr)) 

Errors 

Ignoring function, function requires state (PHOP, *, STOP, *) 
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GENERALIZED STRUCTURE ELEMENT 

Name 

GENERALIZED STRUCTURE ELEMENT (GSE) - create a GSE 

Syntax 

void 

pgse( id, gse) 

Pint id; GSE identifier 

PgsejJata *gse; GSE data record 

Required PHIGS Operating States 

(PHOP, *, STOP, *) 

Input Parameters 

id The identifier of the generalized structure element to insert. 

Recognized identifiers defined in esgdp.h are: 

PES_GSE_SPHEREJ*ADIUS 

PES_GSE_SPHERE_DIVISIONS 

PESJ3SE_CYLINDER_RADIUS 

PES_GSE__CYLINDERJDIVISIONS 

PES__GSE_STEREO_VIEWJNDICES 

PES__GSE_FILLAREAJTOLERANCE 

PES_GSE_FRONT_BACK_DISTINGUISH 

PES_GSE_POLYLSNE_QUALSTY 

PES_GSE_LINEPATTERN_MASK 

PES_GSE_EDGEPATTERN_MASK 

PESJ3SEJNFORMATION 

PES_GSE_TRANSPARENCY 

gse A pointer to a PgsejJata union containing the information 

needed to perform the function specified by id. 
Pgse_data is defined in phigs.h as: 

typedef union { 
struct { 

Pint unused; 

} gsejl ; 

Pdata unsupp; /* Unsupported GSE data */ 

} Pgse_data; 
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The unsupp field in the Pgse_data structure is of type Pdata which is de- 
fined in phigs.h. 



typedef struct { 




s!ze_t size; 


/* size of data */ 


char *data; 


/* pointer to individual GSE data */ 


} Pdata; 




rcription 





GSE creates an implementation-dependent structure element. On the ESV 
Series Workstations a GSE element may be used to: 

Set the radius of spheres. 
(PES_GSE_SPHERE_RADIUS) 

Set the precision used to render spheres. 
(PES_GSE_SPHERE_DIVISIONS) 

Set the radius of cylinders. 
(PES_GSE_CYLINDER_RADIUS) 

Set the precision used to render cylinders. 
(PES_GSE_CYLINDER_DMSIONS) 

Set the left and right-eye view indices for stereo. 
(PES_GSE_STEREO_VIEW_INDICES) 

Set the offset distance that separates polylines and fillareas 
that lie in the same plane. 
(PES_GSE_FILLAREA_TOLERANCE) 

Set the offset value that separates fillarea front and back faces. 
(PES_GSE_FRONT_BACK_DISTINGUISH) 

Set the polyline quality as jaggy or smooth. 
(PES_GSE_POLYLINE_QUALITY) 

Set the line pattern mask. 
(PES_GSE_LINEPATTERN_MASK) 

Set the edge pattern mask. 
(PES_GSE_EDGEPATTERN_MASK) 

Establish a traversal information ID elementor matrix information 

element. 

(PES_GSE_INFORMATION) 

Set the surface transparency attribute. 
(PES_GSE_TRANSPARENCY) 
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Execution 

If the current edit mode is insert, then GSE is inserted into the currently open 
structure after the element currently pointed to by the element pointer. If the 
edit mode is replace, then GSE replaces the element pointed to by the element 
pointer. In either case, the element pointer is updated to point to the new ele- 
ment. 

Individual GSEs 

Each individual GSE is provided its own structure type to hold the data 
unique to it. The structure should be pointed at by the data field in the Pdata 
structure described above. Following is a description of each GSE and its as- 
sociated data types and definitions. All of these are structures are defined in 
esgdp.h. 

Sphere Radius 

The Sphere Radius GSE establishes the radii of all spheres that do not have 
radius data as part of the sphere GDP element. The radius should be placed in 
the radius field of the following structure: 

typedef struct { 

Pf loat radius; /* default radius for spheres */ 

} Pgse_sphere__radius_data; 

Sphere Divisions 

The Sphere Divisions GSE establishes the precision with which spheres will 
be drawn. Spheres will be drawn with div number of latitude lines and a cor- 
responding number of longitude lines. The number of divisions should be 
placed in the div field of the following structure: 

typedef struct { 

Pint div\ /* number of lat. and long, divisions */ 

} Pgse_sphere„dlvjfata; 

Cylinder Radius 

The Cylinder Radius GSE establishes the radii of all cylinders that do not 
have radius data as part of the cylinder structure element. The radius should 
be placed in the radius field of the following structure: 

typedef struct { 

Pf loat radius; /* default radius for cylinders */ 
} Pgse_cyl_radius_jlata; 
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Cylinder Divisions 

The Cylinder Divisions GSE establishes the number of sides (2*cf/V+ 1) that 
the cylinder will be broken into for rendering. A number less than defaults 
to a reasonable value. The number of divisions should be placed in the div 
field of the following structure: 

typedef struct { 

Pint div 9 /* number of lat. and long, divisions */ 

} Pgse_cyl_div_data; 

Stereo View Indices 

The Stereo View Indices GSE provides a more general version of the PHIGS 
SET_VIEWJNDIGES structure element, and can be used in place of the 
SET_VIEWJNDIGES structure element. This element stores three view table 
indices: a mono view index that will be used by the structure walker if the 
structure is being displayed on a regular monoscopic screen; and left and 
right view indices that are used by the structure walker if the structure is be- 
ing displayed on a stereo screen. 

typedef struct { 

Pint mono; 

Pint left-, 

Pint right, 
} Pgse_stereo_viewJndices; 

Polylines Over Fillarea Tolerance 

This GSE is used to make polylines appear in front of fillareas when they may 
lie on the same plane as the fillarea. All polylines and fillarea edges are 
moved slightly forward relative to the fillarea interior. This GSE defines how 
far forward they are moved. By setting a tolerance of 0.0, applications forbid 
polylines from being moved. The tolerance value should be a value between 
-1.0 and 1.0. Lines are moved in NPC space in front of fillareas. The default 
is .003. 

typedef struct { 

Pfloat tolerance", 
} Pgse_fillarea_tolerance; 
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Fillarea Front/Back Face Distinguish 

To avoid ambiguity where the front and back fillareas of a surface meet (that 
is, along the silhouette), back fillareas are moved slightly backwards relative 
to front fillareas. This GSE defines how far back to move back fillareas. The 
distinguish field below is an integer that is subtracted to the back face z val- 
ues before sending them to the z-buffer for testing. A value of 2 (the default) 
is typically sufficient for all back faces. A value of disables any distinguish- 
ing between front and back fillareas. 

typedef struct { 

Pint distinguish; 

} PgseJrontJ>ack__distlnguish; 

The polyline over fillarea tolerance is a float while the front/back face 
distinguish is an integer because tolerance needs to vary depending on the 
model and may be quite large, while a small constant value is sufficient for 
distinguish. 

Polyline Quality 

The Polyline Quality GSE provides a structure element that will enable or 
disable the anti-aliasing of polylines. If the PSMOOTH identifier is used in 
the flag field of the following structure, polylines will be anti-aliased. If the 
PJAGGY identifier is used, polylines will not be anti-aliased. 

typedef enum { 

PSMOOTH, 

PJAGGY 
} Pgse__polyllne_qualityJlag; 

typedef struct { 

Pgse_polyllne__qualityJlag flag; 
} Pgse_polyline_quality; 
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Line Pattern Mask 

This GSE sets the polyline type to a pattern other than the predefined polyline 
types. If the polyline type set by a call to the SETJJNETYPE function is set 
to PES_PLINE_MASK (defined in esgdp.h) the line pattern is taken as de- 
fined by this GSE. The length field of the following structure is the number 
of bits in the pattern, from 1 to 32. Each bit in the pattern represents one pixel: 
if a bit is set to 1 it causes the corresponding pixel to be drawn, if the bit is 
drawing is suppressed. The bits in the pattern begin with the least significant 
bit. 

typedef struct { 

Pint length; /* must be from 1 to 32 */ 

Plong pattern; 

} Pgsejinepattern_mask; 

Edge Pattern Mask 

This GSE sets the fillarea edge type to a pattern other than the predefined 
edge types. If the edge type set by a call to the SET_EDGETYPE function is 
set to PES_PLINE_MASK (defined in esgdp.h) the edge pattern is taken as 
defined by this GSE.The length field of the following structure is the number 
of bits in the pattern, from 1 to 32. Each bit in the pattern represents one pixel: 
if a bit is set to 1 it causes the corresponding pixel to be drawn, if the bit is 
drawing is suppressed. The bits in the pattern begin with the least significant 
bit. 

typedef struct { 

Pint length; /* must be from 1 to 32 */ 

Plong pattern; 

} Pgse_edgepattern_mask; 



ESV Workstation Reference Manual [2.0] 1 - 59 



ES/PEX 



Traversal Information 

The Traversal Information GSE provides a special structure element that will 
only be looked at by the structure walker if a special information traversal has 
been requested (see the X extension routine XGetTraversallnfo). When this 
GSE is traversed, the structure walker buffers either a matrix which is the 
composite local and global matrices, or a user defined ID. If the type field in 
the following structure is set to PESJNFORMATION JMATRiX, then the 
composite matrix is buffered and returned to the application. If the type field 
is set to PESJNFORMATIONJD, then the integer placed in the id field be- 
low is buffered and returned to the application. This functionality has been 
provided to aid molecular modeling applications in doing distance monitor- 
ing and enbrgy calculations. This functionality could also be used in a number 
of other settings, such as collision detection. 

typedef enum { 

PESJNFORMATIONLMATRIX, 

PESJNFORMATIONJD 
} Pesjnformationjype; 

typedef struct { 

Pesjnformationjype type; 
union { 

Pint unused! 

Pint Id; 

}rec; 
} Pgsejnformation^data; 

Transparency 

This GSE sets the transparent attribute for surfaces. The attribute is a float- 
ing point number from 0.0 to 1.0. A value of 1.0 is the most transparent (al- 
most clear). A value of 0.0 turns the transparency functionality off. The data 
field of the Pdata structure should point to the following structure: 

typedef struct „Pgse Jransparency { 

Pfioat transparent, /* Ranges from 0.0 to 1.0 */ 
} Pgse Jransparency; 

Errors 

Ignoring function, function requires state (PHOP s *, STOP, *) 
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SET HLHSR ID 
Name 



SET HLHSR IDENTIFIER - create a structure element to set the current hid- 
den line/hidden surface removal attribute. 

Syntax 

void pset_hlhsrjd ( id ) 

Pint Id; HLHSR identifier 

Required PHIGS Operating States 

(PHOP, *, STOP, *) 

Description 

SET HLHSR IDENTIFIER creates a structure element containing a value for 
the Hidden Line and Hidden Surface Removal (HLHSR) identifier attribute. 
During traversal, this attribute replaces the current HLHSR identifier and is 
applied to all output primitives that follow in the structure network in a work- 
station-dependent way. On the ES V workstation, it can turn z-buffering on 
and off if PHIGS__HLHSR_MODE_ZBUFF is being used. Also, it can be used 
to give special rendering instructions to the graphics processor for drawing 
surfaces that are transparent or lines that lie on polygons. 

The HLHSR identifier in the structure network is used in conjunction with 
the HLHSR mode on the workstation during traversal. Presently, both must be 
on to enable z-buffering Hidden Surface Removal. 

If the current edit mode is insert, then a SET HLHSR IDENTIFIER 
element is inserted into the currently open structure after the element pointed 
to by the current element pointer. If the edit mode is replace, then the new 
SET HLHSR IDENTIFIER element replaces the element pointed to by the 
element pointer. In either case, the element pointer is updated to point to the 
new element. 
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Input Parameter 

id The HLHSR identifier value. Presently supported values are: 

PHIGS JHLHSRJD_OFF Turn off z-buffering. 

PHIGS_HLHSRJD_ON Turn on z-buffering. 

PES_HLHSR_ID_BEG_SURFACES Begin rendering surfaces. 

PES_HLHSRJD_BEG_SURF_EDGES Begin rendering surface 

edges. 

PESJHLHSRJD_BEG__CTHRU Begin rendering 

transparent objects. 

PES_HLHSRJD_BEG_LINES Begin rendering lines. 

Execution 

When the SET HLHSR IDENTIFIER element is traversed, the current HLHSR 
identifier entry in the traversal state list is set to the HLHSR identifier that is 
stored in this element. The current HLHSR identifier is applied to output prim- 
itives that follow in the structure network. 

On the ES V workstation, if the current HLHSR mode is 
PHIGS_HLHSR_MODE_ZBUFF, then the HLHSR identifier will turn z- 
buffering on or off. 

The default state for the HLHSR identifier is PHIGS_HLHSRJD_OFF. 

Special ESV HLHSR IDs 

On the ESV workstation, some images that include the use of transparencies, 
edges on surfaces such as fillareas, or polylines that pass through or are coin- 
cident with surfaces, can exhibit rendering problems. These problems are a 
natural result of trying to anti-alias or blend edges or transparent surfaces with 
the objects that lie behind them in a scene. In order to be done correctiy, anti- 
aliasing or blending must be done after all underlying objects have been 
drawn. Since the ESV does not pre-sort all objects on a pixel basis before 
drawing, problems can appear. These rendering problems can be decreased 
by traversing and rendering primitives in certain groups and in an order that 
provides the best image. The groups are 

• Opaque surfaces. 

• Edges of opaque surfaces. 

• Transparent surfaces and their edges. 

• Polylines. 

The above ordering may or may not be the best for a given image, 
depending on which primitives are in front and which are in back. 



C 



C 



C 



1 - 62 ESV Workstation Reference Manual [2.0] 



ES/PEX 



Note: Transparent surfaces are created by using a 
GSE element PES_GSE_TRANSPARENCY 

in the structure. It specifies a transparency 

value attribute between 0.0 and 1.0. If the 

transparency value is 0.0, transparency is 

turned off. If the transparency value is not 0.0, 

then it is turned on and surface primitives that 

follow in the structure are considered 

transparent. See the documentation on 

GENERALIZEDSTRUCTURE_ELEMENT. 
Two methods of grouping primitives are provided for rendering. Both 
have some speed degradation over the normal rendering method. The first is 
a "vanilla-PHIGS application" method, where we provide special HLHSR 
modes (see the manual page on HLHSR modes, not to be confused with 
HLHSR IDs!) that instruct the structure walker to do multiple traversals in 
order to send primitives to the graphics pipeline in the right order. The second 
is a "smart application" method, where the application intelligently orders 
primitives so that they are traversed in the correct order. 

In the "smart application" method, the application must order the 
structures and the primitives in each structure so that all opaque fillareas, 
triangle_strips, etc. are traversed together. Also, transparent surfaces should 
be grouped together and polylines should be grouped together. The order of 
traversal depends on how the different groups relate to each other in terms of 
z (i.e., which is in front and which in back). No single order may solve all 
problems. You will want to find an order that best fits your application. 
Generally, objects that are further away should be traversed first. 

In addition, in front of each of these groups of primitives the "smart 
application" must place one of the following special HLHSR ID elements: 

PES_HLHSRJD_BEG_SURFACES Begin rendering surfaces. 

PES_HLHSR_ID_BEG_SURF_EDGES Begin rendering edges of 

surfaces. 

PES_HLHSR_ID_BEG_CTHRU Begin rendering transpar- 

ent surfaces. 

PES_HLHSR_ID_BEG_LINES Begin rendering lines. 

These HLHSR IDs tell the structure walker and the graphics pipeline what 
kinds of primitives are coming next and how to deal with them. This "smart 
application" method of doing better renderings gets better performance at run 
time than the "vanilla-PHIGS" method alluded to above, but it requires 
intelligent structure building by the application. 
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Edges | 

Notice that there are different HLHSR IDs for doing edges of surfaces. In or- 
der to do surface edges with the "smart application" method, the application 
must create the structure so that surface primitives are traversed twice, the 
first time to draw the interior of the surface, the second time to draw the sur- 
face edges. 

Note: The HLHSR mode for a workstation is set with 
the SET HLHSR MODE function. 



( 



( 



1 - 64 ESV Workstation Reference Manual [2.0] 



ES/PEX 



SET HLHSR MODE 

Name 

SET HLHSR MODE - set the hidden line and hidden surface removal 
algorithm for a workstation 

Syntax 

void pset_hlhsr__mode ( ws, mode ) 

Pint wsi workstation identifier 

Pint mode; HLHSR mode 

Required PHIGS Operating States 

(PHOP, WSOP, *, *) 

Description 

The SET HLHSR MODE requests a certain Hidden Line and Hidden Surface 
Removal (HLHSR) mode for a workstation. The workstation's current 
HLHSR mode either sets the HLHSR algorithm to be used or it disables all 
HLHSR methods for a workstation. The current HLHSR identifier from the 
structure network is used in conjunction with the HLHSR mode on the work- 
station during traversal. 

On the ESY workstation, the HLHSR mode enables the use of z-buffering, 
or causes special structure traversals to be used to create higher quality 
images: 

CPK Renderings 

This special mode turns on the high-quality, anti-aliased rendering of 
spheres and cylinders. This mode was developed to support molecular 
modeling applications. These renderings are done in software on the host and 
are not real time. 

Multi-Pass Traversals 

On the ES V workstation, some images that include the use of 
transparencies, anti-aliased edges on surfaces such as fillareas, or polylines 
that pass through or are coincident with surfaces, can exhibit rendering 
problems. These problems are a natural result of trying to blend edges or 
transparent surfaces with the objects that lie behind them in a scene. In order 
to be done correctly, anti-aliasing or blending must be done after all 
underlying objects have been drawn. Since the ES V does not pre-sort all 
objects on a pixel basis before drawing, problems can appear. These 
rendering problems can be decreased by traversing and rendering primitives 
in certain groups and in an order that provides the best image. The groups are 
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• Opaque surfaces. 

• Edges of opaque surfaces. 

• Transparent surfaces and their edges. 

• Polylines. 

The above ordering may or may not be the best for a given image, 
depending on which primitives are in front and which are in back. We have 
provided two methods of grouping primitives for rendering. Both have some 
speed degradation over the normal z-buffering HLHSR mode. The first is a 
"vanilla-PHIGS application" method, where we provide special HLHSR 
modes (see below) that instruct the structure walker to do multiple traversals 
in order to send primitives to the graphics pipeline in the desired order. The 
second is a "smart application" method, where the application intelligently 
orders primitives in structures so that they are traversed in the desired order. 

Input Parameters 

ws The identifier of the workstation whose HLHSR mode is being 

set. 

mode The HLHSR mode value. Presently defined values are 

PHIGS_HLHSR_MODE_NONE 

Disable z-buffering. All HLHSR rendering algorithms will be 
disabled with this mode. 

PHIGS_HLHSR_MODE_ZBUFF 

Enable z-buffering. z-buffering is enabled and capable of be- 
ing turned on by the correct HLHSR ID. 

PESJHLHSRJMODE_HCLCPK 

High-Quality Sphere and Cylinder Rendering. This mode 
turns on high-quality, anti-aliased rendering of spheres and 
cylinders, and is important to the molecular modeling indus- 
try. The speed of this type of rendering is much slower than the 
regular HLHSR z-buffering mode. This mode has some restric- 
tions. First, the only primitives that will be rendered under this 
mode are spheres and cylinders (see GDP primitives). Second, 
only orthographic viewing projections can be used, no per- 
spective allowed! Third, the view table index can only be set 
once, at the top of a structure, and cannot be changed. Fourth, 
primitives rendered in this way cannot be picked. 
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PES_HLHSR_MODE_MULTIPASS_xxx 

Rendering Correct Edges on Surfaces and Rendering Trans- 
parencies. This is a group of modes that instruct the structure 
walker to do multiple traversals in a particular order.There can 
be up to three traversals requested, one for doing surfaces, one 
for transparent surfaces, and one for polylines. The letters xxx 
represent various combinations of the letters "S" (for travers- 
ing surfaces), "T" (for traversing transparent surfaces), and 
"L" (for traversing polylines). While none of these modes are 
correct for all applications, the picture will be more correct if 
objects that are further away in z are rendered first so that anti- 
aliased primitives that are nearer in z can be anti-aliased to the 
color of the primitives that are behind them. Also, transparent 
objects should take part of their color from the objects that lie 
behind them and are better rendered after the objects that are 
further away. Because multiple traversals are done, this ren- 
dering method takes longer than the normal z-buffering mode 
(although hardware z-buffering is still turned on for these 
modes). While all possible combinations of traversals do not 
make sense and are not available, many are valid and are be 
listed below. 

Note: Transparent surfaces are created by using a 

GSE element PES_GSE_JRANSPARENCY 

in the structure. It specifies a transparency 
value attribute between 0.0 and 1.0. If the 
transparency value is 0.0, transparency is 
turned off. If the transparency value is not 0.0, 
then it is turned on and surface primitives that 
follow in the structure are considered 
transparent. See the documentation for 
GENERALIZED STRUCTURE ELEMENT. 
PES_HLHSR_MODE_MULTIPASS_ST 

Rendering Surfaces and Transparent Objects Only. This mode 
causes the structure walker in the X Server to make two tra- 
versals, rendering opaque surfaces and their edges first, and 
transparent surfaces last. A traversal pass to render polylines 
is not done and they are left out of the picture. 
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PES_HLHSR__MODE_MULTIPASS_STL 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
trciversals of the workstation, rendering opaque primitives 
such as fillareas and their edges first, transparent objects sec- 
ond, and polylines last. 

PESJH^HSRJWODE_MULTIPASS_SL 

Rendering Correct Edges On Fillareas And Polylines Over 
Fillareas. This mode causes the structure walker in the X Serv- 
er to make two traversals of the structures posted to the work- 
station, rendering opaque surfaces first with their edges and 
polylines last. This makes possible the correct rendering of 
edges on fillareas and the best rendering of anti-aliased lines 
over fillareas. In this mode, surfaces that are transparent are 
not rendered. 

PES_HLHSR_MODE_MULTIPASS„SLT 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
traversals of the workstation, rendering opaque surfaces and 
their edges first, polylines second, and transparent objects last. 
This mode should be used in preference to the STL mode 
above if most polylines and opaque surfaces in the picture are 
further away in z than transparent objects. 

PESJiLHSRJWIODEJMULTIPASSJT 

Rendering Transparent Objects Only. This mode is very simi- 
lar to the above modes, except that the traversal passes to ren- 
der opaque surfaces and polylines are not done and they are 
left out of the picture. Transparent surfaces only are rendered. 

PESJ4LHSR„MODE_MULTIPASSJTS 

Rendering Surfaces and Transparent Objects Only. This mode 
causes the structure walker to make two traversals, rendering 
transparent surfaces first with their edges and opaque surfaces 
second with thwedp^ 
is not done and polylines are left out of the picture. 
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PES_HLHSR_MODE_MULTIPASS_TSL 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
traversals of the workstation, rendering transparent surfaces 
first, opaque surfaces second, and polylines last. This mode 
should be used in preference to the STL mode above if all 
transparent surfaces in the picture are further away in z than 
other objects. 

PES_HLHSR_MODE_MULT!PASS_TL 

Rendering Transparent Objects and Polylines Only. This 
mode is very similar to the above modes, except that the tra- 
versal pass to render non-transparent surfaces is not done and 
they are left out of the picture. Transparent surfaces are ren- 
dered first and opaque surfaces are rendered second. 

PES_HLHSR_MODE_MULTIPASS_TLS 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
traversals of the workstation, rendering transparent surfaces 
first, polylines second, and opaque surfaces such as fillareas 
and their edges last. This mode should be used in preference 
to the STL mode above if all transparent surfaces in the picture 
are further away in z than polylines and other objects. 

PES_HLHSR_MODE_MULTIPASS_LS 

Rendering Opaque Objects and Polylines Only. This mode 
causes the structure walker to make two traversals of the 
workstation, rendering polylines first and opaque surfaces sec- 
ond. The pass to render transparent surfaces is not done and 
they are left out of the picture. This mode should be used in 
preference to the TL mode above if all polylines in the picture 
are further away in z than opaque objects. 

PES_HLHSR_MODE_MULTIPASS_LST 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
traversals of the workstation, rendering polylines first, opaque 
surfaces second, and transparent surfaces last. This mode 
should be used in preference to other three-pass modes if 
polylines are generally furthest away in z, followed by opaque 
surfaces, and then by transparent ones. 
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PES_HLHSRJWODEJWIULTIPASS_LT 

Rendering Transparent Objects and Polylines Only. This 
mode causes polylines to be traversed first, followed by trans- 
parent surfaces. The pass to render opaque surfaces is not done 
and they are left out of the picture. This mode should be used 
in preference to the TL mode above if all polylines in the pic- 
ture are further away in z than transparent objects. 

PESJiLHSR_MODE_MULTIPASSJ-TS 

Rendering Transparent Objects With Surfaces and Lines. This 
mode causes the structure walker in the X Server to make three 
traversals of the workstation, rendering polylines first, trans- 
parent surfaces second, and opaque surfaces last. This mode 
should be used in preference to other three-pass modes if 
polylines are generally furthest away in z, followed by trans- 
parent surfaces, and then by opaque surfaces. 

Note 

To avoid the cost of multiple traversals when drawing fillarea edges, 
polylines over fillareas and transparent objects, the application can either use 
the standard z-buffering mode (and expect an occasional anomaly in the im- 
age), or it can use a "smart application" method where the structure is created 
in such a way that filled surfaces are traversed together, as are transparent ob- 
jects and polylines. The application must then insert special HLHSR ID ele- 
ments in the structure that provide special instructions to the structure walker. 

This will cause edges, transparent objects and lines to be rendered more 
successfully in a single traversal under the usual 
PHIGS_HLHSR_MODE_ZBUFFmode. See SET HLHSR IDENTIFIER for 

details. 



c 



c 



c 
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Execution 

If the requested HLHSR mode value is supported on the specified workstation, 
then SET HLHSR MODE immediately sets the requested HLHSR mode entry 
in the PHIGS workstation state list to the specified mode. The effect of calling 
SET HLHSR MODE is not visible until the requested HLHSR mode replaces 
the current HLHSR mode. The time at which this occurs depends on the work- 
station's display update state. 

This assignment is performed immediately and the HLHSR update state is 
set to Not Pending if any one of the following is true: 

1) The workstation display update state allows update. 

2) The workstation modification mode is any value other than No Imme- 
diate Visual Effect, and the dynamic modification accepted for HLHSR 
mode entry in the workstation description table is set to Immediate. 

3) The display space empty status in the workstation state list is EMPTY. 

Otherwise, the HLHSR update state is set to Pending and the requested 
HLHSR mode will not replace the current HLHSR mode until the next time the 
workstation is updated. The HLHSR update state will be set to Not Pending at 
that time. 
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PHIGS Input with ESV Devices 

This section describes how to use PHIGS input to access the knob box (control 
dials), button box and Spaceball devices on an ESV workstation. This is not 
intended to be a PHIGS input tutorial. 

Refer to the manual pages for INITIALIZE CHOICE (3), 
INITIALIZE LOCATOR (3), INITIALIZE PICK (3), INITIALIZE STRING (3), 
INITIALIZE STROKE (3), and INITIALIZE VALUATOR (3) for a complete 
description of all the available PHIGS devices. 

Initializing the Knob Box 

The ESV knob box is a set of eight PHIGS valuator devices, numbers 11-18. 
The knobs are numbered from left to right and top to bottom. The ESV knob 
box implementation supports two PETs (Prompt and Echo Types): 

• PET 1 provides an echo of the current knob value on the label above 
the knob when the device is active. This value is a floating point num- 
ber in the range specified by the high and low values in the Pval_data 
structure. 

• PET -1 allows the application to define the knob label in the 
INITIALIZE VALUATOR and INITIALIZE VALUATOR 3 functions. 
This label will be displayed when the device is active. The 
pets.pet_u1 .label field of the PvaLdata structure is used to specify 
the label. The other fields of the structure are ignored by this device. 

Initializing the Button Box 

The ESV button box is a single PHIGS choice device number 3. The values 
returned range from 1-32. The buttons are numbered left to right and top to 
bottom. The ESV button box implementation supports three PETs: 

• PET 1 will echo the device by turning on the LED in the button when 
the button is pressed and turning off the LED when the button is re- 
leased. 

• PET 2 will echo the device by turning on the button LEDs correspond- 
ing to the PPR__ON values specified in the prompts list in the 
Pcholce__data structure when the device is active. The prompts list 
can ibe from 1 to 32 in length. Values in the list beyond the 32nd wffl 
be ignored. 

• P ET -1 will echo the device by turning on the button LED the first time 
a button is pressed and turning of the LED the next time the same but- 
ton is pressed when the device is active. There is no data record asso- 
ciated with this PET. 



( 



C 



C 
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Initializing Spaceball 

The ESV Spaceball is a single PHIGS choice device number 2 for Spaceball 
buttons and a single PHIGS string device number 2 for Spaceball motion. The 
string is an encoded form of the six floating pgint numbers returned by Spa- 
ceball. These values can be decoded with a sscanf function call using the for- 
mat "%d,%d,%d,%d,%d,%d" and six floating point variables to receive the 
values. 

The ESV Spaceball implementation supports only PET for both the choice 
and string device: 

• PET 1 has no echo on either the choice or string device. 
Input Processing 

There are no special considerations for processing input from ESV devices. 
They all follow standard PHIGS input conventions with the exception that the 
ESV Spaceball string device returns six floating point values encoded as a 
string. 

Knob Box Example 



P limit 


echo area; 


Pval_data 


val data; 


float 


delay = 2. 


Pint 


dev, ws; 


Pin class 


class; 


Pfloat 


val; 


int 


done = ; 



/* init echo area. This is required even thought it is ignored */ 
echo_area . x_min = 0.0; 
echo_area . x_max = 1.0 
echo_area . y_min =0.0 
echo_area . y_max = 1.0 

/* initialize knobs 1,2 and 3 with PET -1 and labels */ 

val_data.low = -1.0; 

val_data.high = 1.0; 

val_dat a. pet s .pet_ul .format = NULL; 

val_data .pets .pet__ul . low_label = NULL; 

val_data.pets .pet_ul .high_label = NULL; 

val_data. pet s .pet_ul .label = "Rotate X"; 

pinit_val(l, 11, 0.0, -1, &echo_area, &val_data) ; 

val_data.pets .pet_ul .label = "Rotate y"; 

pinit_val(l, 12, 0.0, -1, &echo_area, &val_data) ; 
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val_data.pets .pet_ul .label = "Rotate z"; 
pinit_val(l, 13, 0.0, -1, &echo_area, &val_data) ; 

/* set knobs 1, 2, and 3 in event mode */ 
pset_val_mode ( 1, 11, POP_EVENT, PSWITCH_ECHO) ; 
pset_val_mode ( 1, 12, POP_EVENT, PSWITCH_ECHO) ; 
pset_val_mode ( 1, 13, POP_EVENT, PSWITCH_ECHO) ; 

while ( !done) 
{ 

pawait_event ( delay, &ws, &class, &dev ); 

switch (class) 

{ 

default : 

case PINJSTONE: 

break; 
case PIN_VAL: 
pget_val ( &val ) ; 
/* process knob events */ 
break; 
} 
} 
} 



C 



Button Box Example 



{ 



Pchoice_data cho_data; 

P limit echo_area; 

float delay = 2.0; 

Pint dev, ws; 

Pin_class class; 

Pint cho; 

Pin_status status; 

int done = 0; 

/* init echo area. This is required even thought it is ignored */ 
echo_area .x_min =0.0; 
echo_area . x_max = 1.0; 
echo_area . y_min =0.0; 
echo_area.y_max =1.0; 



C 
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/* initialize PET 2 with LEDs 1-9 on and the rest off */ 

cho_data . pet_r2 . numjprompts = 32 ; 

cho_da t a. pet_r2 .prompts = (Ppr_switch *)calloc(32 f 

sizeof (Ppr_switch) ) ; 
for (i = 0; i < 9; i++) { 

cho_data .pet_r2 .prompts [i] = PPR_ON; 
} 
pinit_choice (l f 3, PIN_STATUS_OK, 1, 2, &echo_area, &cho_data) , 

/* set buttons in event mode */ 

pset_choice_mode ( 1, 3, POP_EVENT r PSWITCH_ECHO) ; 

while ( !done) 
{ 

pawait_event ( delay, &ws, &class, &dev ); 

switch (class) 

{ 

default : 

case PIN_NONE: 

break; 
case PIN_CHOICE: 
pget_choice ( &status, &cho) ; 
switch (status) 
{ 

case PIN_STATUS_OK: 
/* process button box events */ 
break; 
} 
break; 



} 

Spaceball Example 


{ 

int 


done = ; 


float 


delay =2.0 


Pint 


dev, ws; 


Pin__class 


class; 


char 


str[100] ; 


Pint 


cho; 



Pin status status; 
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/* set space ball in event mode, it is both a chaice and string 

* device. There is no need to initialize 

*/ 
pset_choice_mode ( 1, 2, POP_EVENT, PSWITCH_ECHO) ; 
pset_string_mode( 1, 2, POP_EVENT, PSWITCH_ECHO) ; 

while (!done) 
{ 

pawait_event ( delay, &ws, &class, &dev ); 

switch (class) 

{ 

default : 

case PIN_NONE: 

breaks- 
case PIN__STRING: 
{ 

int axis [6] ; 

pget_string(str) ; 

sscanf (str, "%d, %d, %d, %d f %d, %d" p 

&axis [0] f 

&axis [1] , 

&axis [2] , 

&axis[3] r 

&axis [4] , 

Saxis [5] 

); 

/* process spaceball motion event */ 

break; 
} 
case PIN_CHOICE: 
pget_choice ( &status f &cho) ; 
switch (status) 

{ 

case PIN_STATUS_OK: 
/* process spaceball button events */ 
break; 
} 
break; 

} 
} 



C 



} 



( 



( 
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Function Numbers 



The function numbers listed in the left-hand column are returned by error 
messages. The corresponding symbolic name is listed in the middle column, 
and the corresponding function name is listed in the right-hand column. 

In the following list, functions shown in bold are supported by the ESV 
Workstation, and functions shown in italics are not currently supported by the 
ESY Workstation. 



No. 


Symbolic Name 


Function Name 


-5 


Pfn_openpex 


OPEN PEX 





Pfn_openphigs 


OPEN PHIGS 


1 


Pfnclosephlgs 


CLOSE PHIGS 


2 


Pfn_openws 


OPEN WORKSTATION 


3 


Pfn_closews 


CLOSE WORKSTATION 


4 


Pfn_redrawallstruct 


REDRAW ALL STRUCTURES 


5 


Pfn_updatews 


UPDATE WORKSTATION 


6 


Pfn_setdisplayupdatest 


SET DISPLAY UPDATE STATE 


7 


Pfn_messag@ 


MESSAGE 


8 


Pfn_polyline3 


POLYLINE 3 


9 


Pfn_polyline 


POLYLINE 


10 


Pfn_polymarker3 


POLYMARKER 3 


11 


Pfn_po!ymarker 


POLYMARKER 


12 


Pfn_text3 


TEXT 3 


13 


Pfnjext 


TEXT 


14 


Pfn_annotationfextrelative3 


ANNOTATION TEXT RELATIVE 3 


15 


Pfn_annotationtextrelative 


ANNOTATION TEXT RELATIVE 


16 


Pfn_fillarea3 


FILL AREA 3 


17 


Pfnjillarea 


FILL AREA 


18 


Pfn_fillareaset3 


FILL AREA SET 3 


19 


Pfnjillareaset 


FILL AREA SET 


20 


Pfn_cellarray3 


CELL ARRAY 3 


21 


Pfn_cellarray 


CELL ARRAY 


22 


Pfn_gdp3 


GENERALIZED DRAWING PRIMITIVE 3 


23 


Pfn_gdp 


GENERALIZED DRAWING PRIMITIVE 


24 


Pfn_setllneind 


SET POLYLINE INDEX 


25 


Pfn_setmarkerind 


SET POLYMARKER INDEX 
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No. 


Symbolic Name 


Function Name 


26 


Pfn_settextind 


SET TEXT INDEX 


27 


Pfn_setintind 


SET INTERIOR INDEX 


28 


Pfn_setedgeind 


SET EDGE INDEX 


29 


Pfn_setlinetype 


SET LINETYPE 


30 


Pfn_setlinewidth 


SET LINEWIDTH SCALE FACTOR 


31 


Pfn_setlinecolourind 


SET POLYLINE COLOUR INDEX 


32 


Pfn_setmarkertype 


SET MARKER TYPE 


33 


Pfn__setmarkersize 


SET MARKER SIZE SCALE FACTOR 


34 


Pfn_setmarkercolourind 


SET POLYMARKER COLOUR INDEX 


35 


Pfn_settextfont 


SET TEXT FONT 


36 


Pfn_settextprec 


SET TEXT PRECISION 


37 


Pfn_setcharexpan 


SET CHARACTER EXPANSION 
FACTOR 


38 


Pfn_setcharspace 


SET CHARACTER SPACING 


39 


Pfn_settextcolourind 


SET TEXT COLOUR INDEX 


40 


Pfn_setcharheight 


SET CHARACTER HEIGHT 


41 


Pfn_setcharup 


SET CHARACTER UP VECTOR 


42 


Pfn_settextpath 


SET TEXT PATH 


43 


Pfn_settextalign 


SET TEXT ALIGNMENT 


44 


Pfn_setannotationcharheight 


SET ANNOTATION TEXT CHARACTER 
HEIGHT 


45 


Pfn_setannotationcharup 


SET ANNOTATION TEXT CHARACTER 
UP VECTOR 


46 


Pfn_setannotatlonpath 


SET ANNOTATION TEXT PATH 


47 


Pfn_setannotationalign 


SET ANNOTATION TEXT ALIGNMENT 


48 


Pfn_setannotationstyle 


SET ANNOTATION STYLE 


49 


Pfn_setlntstyle 


SET INTERIOR STYLE 


50 


Pfn_setintstyleind 


SET INTERIOR STYLE INDEX 


51 


Pfn_setintcolourind 


SET INTERIOR COLOUR INDEX 


51 


Pfn_setedgeflag 


SET EDGE FLAG 


53 


Pfn_setedgetype 


SET EDGETYPE 


54 


Pfn_setedgewidth 


SET EDGEWIDTH SCALE FACTOR 


55 


Pfn_setedgecolourind 


SET EDGE COLOUR INDEX 


56 


Pfn_setpatsize 


SET PATTERN SIZE 



c 



( 



( 
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No. 


Symbolic Name 


Function Name 


57 


Pfn_setpatrefptvectors 


SET PATTERN REFERENCE POINT 
AND VECTORS 


58 


Pfn_setpatrefpt 


SET PATTERN REFERENCE POINT 


59 


Pfn_addnameset 


ADD NAMES TO SET 


60 


Pfrwemovenameset 


REMOVE NAMES FROM SET 


61 


Pfn_setindivasf 


SET INDIVIDUAL ASF 


62 


Pfn_set!inerep 


SET POLYLINE REPRESENTATION 


63 


Pfnsetmarkerrep 


SET POLYMARKER 
REPRESENTATION 


64 


Pfn_settextrep 


SET TEXT REPRESENTATION 


65 


Pfn__setintrep 


SET INTERIOR REPRESENTATION 


66 


Pfn_setedgerep 


SET EDGE REPRESENTATION 


67 


Pfn_setpatrep 


SET PATTERN REPRESENTATION 


68 


Pfn_setcolourrep 


SET COLOUR REPRESENTATION 


69 


Pfn__sethilightfilter 


SET HIGHLIGHTING FILTER 


70 


Pfn setinvisfilter 


SET INVISIBILITY FILTER 


71 


Pfn setcolourmodel 


SET COLOUR MODEL 


72 


Pfn sethlhsrid 


SET HLHSR IDENTIFIER 


73 


Pfn sethlhsrmode 


SET HLHSR MODE 


74 


Pfn_setlocaltran3 


SET LOCAL TRANSFORMATION 3 


75 


Pfn setlocaltran 


SET LOCAL TRANSFORMATION 


76 


Pfn_setglobaltran3 


SET GLOBAL TRANSFORMATION 3 


77 


Pfn_setglobaltran 


SET GLOBAL TRANSFORMATION 


78 


Pfn_setmodelclipvolume3 


SET MODELLING CLIPPING VOLUME 3 


79 


Pfn_setmodelclipvolume 


SET MODELLING CLIPPING VOLUME 


80 


Pfn_setmodelclipindicator 


SET MODELLING CLIPPING INDICATOR 


81 


Pfn_restoremodelclipvolume 


RESTORE MODELLING CLIPPING 



82 Pfn_setvlewlnd 

83 Pfn_setvlewrep3 

84 Pfnsetviewrep 

85 Pfnsetviewtraninputpri 

86 Pfn_setwswlndow3 

87 Pfn setwswindow 



VOLUME 

SET VIEW INDEX 

SET VIEW REPRESENTATION 3 

SET VIEW REPRESENTATION 

SET VIEW TRANSFORMATION INPUT 
PRIORITY 

SET WORKSTATION WINDOW 3 

SET WORKSTATION WINDOW 
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No. Symbolic Name 

88 Pfn_setwsvIewport3 

89 Pfn_s@twsvlewport 

90 Pfn_openstruct 

91 Pfn_closestruct 

92 Pfn_executestrucf 

93 Pfnjabel 

94 Pfn_app!icationdata 

95 Pfn_gse 

96 Pfn_setedltmode 

97 Pfn_copyallelemsstruct 

98 Pfn__setelemptr 

99 Pfn_offs@telemptr 

1 00 Pf n_s@t elempt rlab@l 

101 Pfn_d©lel@m 

102 Pfnjielelemrange 

103 Pf o_ deleiemslabals 

104 Pfn_empty$truct 

105 Pfnjfelstruct 

106 Pfn_d@lstructnet 

107 Pfn_d@lallstruct 

108 Pfn__changestructid 

109 Pfn_changestructref 

110 Pfn_changestructfdref 

1 1 1 Pf n_poststruct 

112 Pf n_unpoststruct 

113 Pf n_unpostallstrucf 

114 Pfn_op@narfile 

115 Pfn_closearfile 

116 Pfn_arstruct 

117 Pfn_arstructnet 

118 Pfn arallstruct 



Function Name 

SET WORKSTATION VIEWPORT 3 

SET WORKSTATION VIEWPORT 

OPEN STRUCTURE 

CLOSE STRUCTURE 

EXECUTE STRUCTURE 

LABEL 

APPLICATION DATA 

GENERALIZED STRUCTURE ELEMENT 

SET EDIT MODE 

COPY ALL ELEMENTS FROM 
STRUCTURE 

SET ELEMENT POINTER 

OFFSET ELEMENT POINTER 

SET ELEMENT POINTER AT LABEL 

DELETE ELEMENT 

DELETE ELEMENT RANGE 

DELETE ELEMENTS BETWEEN 
LABELS 

EMPTY STRUCTURE 

DELETE STRUCTURE 

DELETE STRUCTURE NETWORK 

DELETE ALL STRUCTURES 

CHANGE STRUCTURE IDENTIFIER 

CHANGE STRUCTURE REFERENCES 

CHANGE STRUCTURE IDENTIFIER 
AND REFERENCES 

POST STRUCTURE 

UNPOST STRUCTURE 

UNPOST ALL STRUCTURES 

OPEN ARCHIVE FILE 

CLOSE ARCHIVE FILE 

ARCHIVE STRUCTURES 

ARCHIVE STRUCTURE NETWORKS 

ARCHIVE ALL STRUCTURES 



( 



( 



C 
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No. Symbolic Name 

119 Pf n_setconf res 

1 20 Pf n_retrievestructids 

121 Pf n_retrievestrucf 

1 22 Pf n_retrievestructnet 

123 Pfnjetrieveallstruct 

1 24 Pf n_retrieveancesstruct 

1 25 Pf n_retrievedescstruct 

126 Pfn_delstructar 

1 27 Pf n_delstruct netar 

128 Pfn delallstructar 



129 Pfn_ 

130 Pfn_ 

131 Pfn_ 

132 Pfn_ 

133 Pfn_ 

134 Pfn_ 

135 Pfn. 

136 Pfn_ 

137 Pfn_ 

138 Pfn_ 

139 Pfn_ 

140 Pfn, 

141 Pfn. 

142 Pfn_ 

143 Pfn. 

144 Pfn_ 

145 Pfn. 

146 Pfn. 

147 Pfn 

148 Pfn 



setpickid 

setpickfilter 

jnitlocS 

Initloc 

initstrokeS 

initstroke 

Jnitval3 

initval 

initchoice3 

fnitchoice 

Initpick3 

Jnltpick 

jnitstringS 

initstring 

.setlocmode 

setstrokemode 

setvalmode 

setchoicemode 

setpickmode 

.setsfringmode 



Function Name 

SET CONFLICT RESOLUTION 

RETRIEVE STRUCTURE IDENTIFIERS 

RETRIEVE STRUCTURES 

RETRIEVE STRUCTURE NETWORKS 

RETRIEVE ALL STRUCTURES 

RETRIEVE ANCESTORS OF 
STRUCTURE 

RETRIEVE DESCENDANTS OF 
STRUCTURE 

DELETE STRUCTURES FROM 
ARCHIVE 

DELETE STRUCTURE NETWORKS 
FROM ARCHIVE 

DELETE ALL STRUCTURES FROM 
ARCHIVE 

SET PICK IDENTIFIER 

SET PICK FILTER 

INITIALIZE LOCATOR 3 

INITIALIZE LOCATOR 

INITIALIZE STROKE 3 

INITIALIZE STROKE 

INITIALIZE VALUATOR 3 

INITIALIZE VALUATOR 

INITIALIZE CHOICE 3 

INITIALIZE CHOICE 

INITIALIZE PICK 3 

INITIALIZE PICK 

INITIALIZE STRING 3 

INITIALIZE STRING 

SET LOCATOR MODE 

SETSTROKEMODE 

SET VALUATOR MODE 

SETCHOICEMODE 

SET PICK MODE 

SET STRING MODE 
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No. Symbolic Name 

149 Pfn_reqloc3 

150 Pfiweqloc 

151 Pfn_reqstroke3 

152 Pfn_reqstroke 

153 Pfnjeqval 

154 Pfnjreqchoice 

155 Pfn_reqpick 

156 Pfn_reqslrlng 

157 Pfn_sampleloc3 

158 Pfn_sampleloc 

159 Pfn_samplestroke3 

160 Pfn_samplestroke 

161 Pfn_sampleval 

162 Pfn_samplechoice 

163 Pfn_samplepick 

164 Pfn_samplestring 

165 Pfn_awaitevent 

166 Pfnjlushevents 

167 Pfn_getloc3 

168 Pfn_getloc 

169 Pfn_getstroke3 

170 Pfnjgetstroke 

171 Pfn_getval 

172 Pfn_getchoice 

173 Pfn_getpick 

174 Pfn_getstring 

175 Pfn_whtemf 

176 Pfn_gettypemf 

177 Pfn_readmf 

178 Pfnjnterpret 

179 Pfn_seterrorhandmocJe 

180 Pfn_escape 

201 Pfn_polylineset3data 



Function Name 

REQUEST LOCATOR 3 

REQUEST LOCATOR 

REQUEST STROKE 3 

REQUEST STROKE 

REQUEST VALUATOR 

REQUEST CHOICE 

REQUEST PICK 

REQUEST STRING 

SAMPLE LOCATOR 3 

SAMPLE LOCATOR 

SAMPLE STROKE 3 

SAMPLE STROKE 

SAMPLE VALUATOR 

SAMPLE CHOICE 

SAMPLE PICK 

SAMPLE STRING 

AWAIT EVENT 

FLUSH DEVICE EVENTS 

GET LOCATOR 3 

GET LOCATOR 

GET STROKE 3 

GET STROKE 

GET VALUATOR 

GET CHOICE 

GET PICK 

GET STRING 

WRITE ITEM TO METAFILE 

GET ITEM TYPE FROM METAFILE 

READ ITEM FROM METAFILE 

INTERPRET ITEM 

SET ERROR HANDLING MODE 

ESCAPE 

POLYLINE SET 3 WITH DATA 



C 



( 



c 
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No. Symbolic Name 

202 PfnJillareaSdata 

203 Pfn_fillareaset3data 

205 Pfn_tri3data 

206 Pfn_quad3data 

207 Pfn_polyhedron3data 

208 Pfn_nunibspcurv 

210 Pfn_nunibspsurf 

211 Pfn_extcellarray3 

212 Pfn_compfillareasetgnorm 



ES/PEX 

Function Name 

FILL AREA 3 WITH DATA 

FILL AREA SET 3 WITH DATA 

TRIANGLE STRIP 3 WITH DATA 

QUADRILATERAL MESH 3 WITH DATA 

POLYHEDRON 3 WITH DATA 

NON-UNIFORM B-SPLINE CURVE 

NON-UNIFORM B-SPLINE SURFACE 

EXTENDED CELL ARRAY 3 

COMPUTE FILL AREA SET 
GEOMETRIC NORMAL 



213 


Pfn_setdcueind 


SET DEPTH CUE INDEX 


216 


Pfn_setareaprop 


SET AREA PROPERTIES 


217 


Pfnsetbackareaprop 


SET BACK AREA PROPERTIES 


218 


Pfn_setlineshadmethod 


SET POLYLINE SHADING METHOD 


220 


Pfn_setbackintstyle 


SET BACK INTERIOR STYLE 


221 


Pfn_setbackintstyleind 


SET BACK INTERIOR STYLE INDEX 


222 


Pfn_setintshadmethod 


SET INTERIOR SHADING METHOD 


223 


Pfn_setbacklntshadmethod 


SET BACK INTERIOR SHADING 
METHOD 


224 


Pfn_setintreflecteq 


SET INTERIOR REFLECTANCE 
EQUATION 


225 


Pfn_setbackintreflecteq 


SET BACK INTERIOR REFLECTANCE 
EQUATION 


226 


Pfn_setlightsrcstate 


SET LIGHT SOURCE STATE 


227 


Pfnsetfacedistgmode 


SET FACE DISTINGUISHING MODE 


228 


Pfnsetfacecullmode 


SET FACE CULLING MODE 


229 


Pfn_seflinecolour 


SET POLYLINE COLOUR 


230 


Pfn_sefmarkercolour 


SET POLYMARKER COLOUR 


231 


Pfn_settextcolour 


SET TEXT COLOUR 


232 


Pfn_setintcolour 


SET INTERIOR COLOUR 


233 


Pfn_setbacklnfcolour 


SET BACK INTERIOR COLOUR 


234 


Pfn_setedgecolour 


SET EDGE COLOUR 


235 


Pfn_setcurveapprox 


SET CURVE APPROXIMATION 



CRITERIA 
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No. Symbolic Name 

236 Pfn_settrimcurvapprox 

237 Pfn_setsurfapprox 

239 Pfn_setextliner@p 

240 Pfn_setextmark@rr@p 

241 Pfn_setextt@xtr©p 

242 Pfn_setext©dg©rep 

243 Pfn_s@tgenintr@p 

245 Pfn_setextpatrep 

246 Pfn_s@tdcu@r©p 

247 Pfn_setllghtsrcr@p 



Function Name 

SET TRIMMING CURVE 
APPROXIMATION CRITERIA 

SET SURFACE APPROXIMATION 
CRITERIA 

SET EXTENDED POLYLINE 
REPRESENTATION 

SET EXTENDED POLYMARKER 
REPRESENTATION 

SET EXTENDED TEXT 
REPRESENTATION 

SET EXTENDED EDGE 
REPRESENTATION 

SET EXTENDED INTERIOR 
REPRESENTATION 

SET EXTENDED PATTERN 
REPRESENTATION 

SET DEPTH CUE REPRESENTATION 

SET LIGHT SOURCE 
REPRESENTATION 



C 



c 
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Error Messages 



The numbers listed in the left-hand column are returned by error messages. 
The corresponding symbolic name is listed in the middle column, and the cor- 
responding error description is listed in the right-hand column. 



Error 


Symbolic Name 


Description 


-317 


PXBADIMPL 


X Bad Implementation Error. 


-316 


PXBADLENGTH 


X Bad Length Error. 


-315 


PXBADNAME 


X Bad Name Error. 


-314 


PXBADIDCHOICE 


X Bad ID Choice Error. 


-313 


PXBADGC 


X Bad GC Error. 


-312 


PXBADCOLOR 


X Bad Colour Error. 


-311 


PXBADALLOC 


X Bad Alloc Error. 


-310 


PXBADACCESS 


X Bad Access Error. 


-309 


PXBADDRAWABLE X Bad Drawable Error. 


-308 


PXBADMATCH 


X Bad Match Error. 


-307 


PXBADFONT 


X Bad Font Error. 


-306 


PXBADCURSOR 


X Bad Cursor Error. 


-305 


PXBADATOM 


X Bad Atom Error. 


-304 


PXBADPIXMAP 


X Bad Pixmap Error. 


-303 


PXBADWINDOW 


X Bad Window Error. 


-302 


PXBADVALUE 


X Bad Value Error. 


-301 


PXBADREQUEST 


X Bad Request Error. 


-264 


PPEXOCE 


PEX output command error. 


-263 


PPEXSE 


PEX structure error. 


-262 


PPEXSCE 


PEX search context error. 


-261 


PPEXRE 


PEX renderer error. 


-260 


PPEXPCE 


PEX pipeline context error. 


-259 


PPEXPME 


PEX pick measure error. 


-258 


PPEXPWE 


PEX PHIGS workstation error. 


-257 


PPEXFE 


PEX font error. 


-256 


PPEXPE 


PEX path error. 


-255 


PPEXNSE 


PEX name set error. 


-254 


PPEXLTE 


PEX lookup table error. 


-253 


PPEXLE 


PEX label error. 
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-252 PPEXFPFE 

-251 PPEXRSE 

-250 PPEXCTE 

-202 PPXALLOC 

-201 PPEXNOPEX 

-200 PPEXNOXSRVR 

-167 PEMAXCRWS 



165 PEBADNEDGE 



-164 PEBADNVTX 



-163 PENOEFLAG 



-162 PENOVFLAG 



-161 PENOFFLAG 



-160 PENOFUNC 



-159 PERNOINFO 



-157 PENOGDP 



156 PENOFONTCS 

-155 PEBADCHARSET 
-153 PELENGTHLZ 



Description 

PEX floating point format error. 

PEX rendering state error. 

PEX colour type error. 

Ignoring function. An X allocation error has 
occurred. 

Ignoring function. The specified X Server does 
not support a compatible PEX extension. 

Ignoring function. Cannot connect to the desig- 
nated or default server. 

Ignoring function. Opening this workstation 
would exceed the maximum number of simul- 
taneously open canvas region workstations on 
a canvas. 

Ignoring function. The length of specified edge 
data lists is inconsistent with the length of 
corresponding vertices lists. 

Ignoring function. The specified number of 
vertices or sets of vertices is less than 0. 

Ignoring function. The specified edge flag is 
invalid. 

Ignoring function. The specified vertex flag is 
invalid. 

Ignoring function. The specified facet flag is 
invalid. 

Ignoring function. The specified function is not 
available on the specified workstation. 

Ignoring function. The requested information 
is not available. 

Warning. The specified GDP is not available 
on one or more workstations in this implemen- 
tation. The GDP will be processed by those 
workstations on which it is available. 

Ignoring function. Specified font is not avail- 
able for character set. 

Specified character set is invalid. 

List length is less than 0. will be used. 



C 



( 
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Symbolic Name 


-152 


PENOTIMPL 


-151 


PEBADNAME 


-150 


PEBADNPTS 


-100 


PEWSTBOUND 


-57 


PESHMEM 


-55 


PENOFONT 


-54 


PENOSPF1LE 


-53 


PEBADFPATH 


-52 


PEPATHTOOLONG 


-51 


PESRVRFILE 


-50 


PECOMM 


-6 


PENOTRAVMEM 


-2 


PEEXEC 


-1 


PECOMCREAT 





PNO_ERROR 


1 


PENOTCL 


2 


PENOTPHOP 


3 


PENOTWSOP 


4 


PENOTPHOPCL 


5 


PENOTSTOP 



Description 

Ignoring function. Not implemented. 

Ignoring function. Nameset or filter contains 
name outside supported range. 

Ignoring function. The specified number of 
points or sets of points is less than 0. 

Ignoring function. Workstation type is a de- 
fault type or bound to a workstation and cannot 
be modified. 

Kernel not configured with shared-memory. 
IPC facility needed for PEX-SI communication. 

Ignoring function. Cannot open PHIGS. Cannot 
open font files. 

Ignoring function. Cannot locate SI support 
file. 

Ignoring function. SI support file path invalid. 

Ignoring function. PEXAPIDIR path is too 
long. 

Ignoring function. Cannot open PHIGS. Cannot 
locate SI file phigsmon. 

Communication error. 

Could not allocate additional dynamic memory 
during structure traversal. 

Ignoring function. Cannot open PHIGS. Cannot 
create server. 

Ignoring function. Cannot open PHIGS. Cannot 
create communication channel. 

No error. 

Ignoring function. Function requires state 
(PHCL,WSCL,STCL,ARCL). 

Ignoring function. Function requires state 
(PHOP,*,Y). 

Ignoring function. Function requires state 
(PHOP,WSOP,V). 

Ignoring function. Function requires state 
(PHOP,WSCL,STCL,ARCL). 

Ignoring function. Function requires state 
(PHOP,*,STOP,*). 
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6 PENOTSTCL 

7 PENOTAROP 

50 PECNIDINV 

51 PENOTAVAIL 



52 PEWSTYPEINV 

53 PEWSIDINUSE 

54 PEWSNOTOP 

55 PENOWSOP 

56 PEWSNOTMO 

57 PEWSCATMI 

58 PEWSNOTMI 

59 PEWSNOTOUT 

60 PEWSNOTIN 

61 PEWSNOTIO 

62 PEWSNOTOO 



Description 

Ignoring function. Function requires state 
(PHOP,*,STCL,*). 

Ignoring function. Function requires state 
(PHOP,*,*,AROP). 

Ignoring function. Connection identifier not 
recognized by the implementation. 

Ignoring function. This information is not yet 
available for this generic workstation type. 
Open a workstation of this type and use the 
specific workstation type. 

Ignoring function. Workstation type not recog- 
nized by the implementation. 

Ignoring function. Workstation identifier 
already is in use. 

Ignoring function. The specified workstation is 
not open. 

Ignoring function. Workstation cannot be 
opened for an implementation dependent rea- 
son. 

Ignoring function. Specified workstation is not 
of category MO. 

Ignoring function. Specified workstation is of 
category MS. 

Ignoring function. Specified workstation is not 
of category Ml. 

Ignoring function. The specified workstation 
does not have output capability (i.e., the work- 
station category is neither OUTPUT, OUTIN, 
nor MO). 

Ignoring function. Specified workstation is not 
of category OUTIN. 

Ignoring function. Specified workstation is 

neither of category INPUT nor of category 

OUTIN. 

Ignoring function. This information is not 

available for this MO workstation type. 



C 



C 
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63 PEWSMAXOPN 

64 PEWSNOGDP 

100 PEBINXLT1 

101 PENOREP 

102 PENOPREDEF 

103 PEWSMAXBNL 

104 PENOLINTP 

105 PENOMKRTP 

106 PENOTXTFP 

107 PENOEDGTP 

108 PENOISTYL 

109 PENOPAT 

110 PEBADCMOD 

111 PENOHLHSR 

112 PEP1NXLT1 

113 PECINXLZ 

114 PEBINDLZ 



Description 

Ignoring function. Opening this workstation 
would exceed the maximum number of simul- 
taneously open workstations. 

Ignoring function. The specified workstation 
type is not able to generate the specified gener- 
alized drawing primitive. 

Ignoring function. The bundle index value is 
less than 1. 

The specified representation has not been 
defined. 

Ignoring function. The specified representation 
has not be predefined on this workstation. 

Ignoring function. Setting this bundle table 
entry would exceed the maximum number of 
entries allowed in the workstation bundle table. 

Ignoring function. The specified linetype is not 
available on the specified workstation. 

Ignoring function. The specified marker type is 
not available on the specified workstation. 

Ignoring function. The specified font is not 
available for the requested text precision on the 
specified workstation. 

Ignoring function. The specified edgetype is 
not available on the specified workstation. 

Ignoring function. The specified interior style 
is not available on the workstation. 

Ignoring function. Interior style PATTERN is 
not supported on the workstation. 

Ignoring function. The specified colour model 
is not available on the workstation. 

Ignoring function. The specified HLHSR mode 
is not available on the specified workstation. 

Ignoring function. The pattern index value is 
less than 1. 

Ignoring function. The colour index value is 
less than 0. 

Ignoring function. The view index value is less 
than 0. 



ESV Workstation Reference Manual [2.0] 



1 -89 



ES/PEX 



Error 


Symbolic Name 


115 


PEBINDL1 


116 


PEBADPAT 


117 


PECADIM 


118 


PEBADCRNG 



119 


PEDCINDLZ 


120 


PEBADDCIND 


122 


PENOLINSHADE 


123 


PENOINTSHADE 


124 


PENOREFEQN 


129 


PEBADLTSSRCfr 


130 


PEINVREFPL 


131 


PENOLTSRCTYP 


132 


PEINVLTANG 


133 


PEINVALLSSIND 


135 


PEINVALLSS 


150 


PEMAXVIEW 



Description 

Ignoring function. The view index value is less 
than 1. 

Ignoring function. One of the dimensions of 
pattern colour array is less than 1. 

Ignoring function. One of the dimensions of 
the colour index array is less than 0. 

Ignoring function. One of the components of 
the colour specification is out of range. The 
valid range is dependent upon the current 
colour mode. 

Ignoring function. Depth cue index is less than 
0. 

Ignoring function. Depth cue index is less than 
1. 

Ignoring function. The specified polyline shad- 
ing method is not available on the workstation. 

Ignoring function. The specified interior shad- 
ing method is not available on the workstation. 

Ignoring function. The specified interior 
reflectance equation is not available on the 
workstation. 

Ignoring function. The light source index is 
less than 1. 

Ignoring function. Invalid reference planes. 
DQMIN > DQMAX. 

Ignoring function. The specified light source 
type is not available on the workstation. 

Ignoring function. The specified spot light 
spread angle is out of range. 

Ignoring function. One of the entries in the 
activation list or the deactivation list is less 
than 1. 

Ignoring function. The same entry exists in 
both the activation and the deactivation list. 

Ignoring function. Setting this view table entry 
would exceed the maximum number of entries 
allowed in the workstation's view table. 



C 
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151 PEBADWIN 

152 PEBADVP 

153 PEBADBOX 

154 PEBADVLIM 

155 PEBADPROVP 

156 PEWINRNG 

157 PEVPRNG 

158 PEFREQBK 

159 PEBADVPN 

160 PEBADVUP 

161 PEBADVIEW 

162 PEBADPRP 

163 PEPRPVP 

164 PEBADBACK 

200 PEIGNSTRUCT 

201 PENOSTRUCT 

202 PENOELEM 

203 PEBADSPATH 



Description 

Ignoring function. Invalid window. XMIN > 
XMAX, YMIN > YMAX, or ZMIN > ZMAX. 

Ignoring function. Invalid viewport. XMIN > 
XMAX, YMIN > YMAX, or ZMIN > ZMAX. 

Ignoring function. Invalid view clipping limits. 
XMIN > XMAX, YMIN > YMAX, or ZMIN > 
ZMAX. 

Ignoring function. The view clipping limits are 
not within NPC range. 

Ignoring function. The projection viewport 
limits are not within NPC range. 

Ignoring function. The workstation window 
limits are not within NPC range. 

Ignoring function. The workstation viewport is 
not within display space. 

Ignoring function. Front plane and back plane 
distances are equal when z-extent of the projec- 
tion viewport is 0. 

Ignoring function. The view plane normal 
vector has length 0. 

Ignoring function. The view up vector has 
length 0. 

Ignoring function. The view up and view plane 
normal vectors are parallel thus the viewing 
coordinate system cannot be established. 

Ignoring function. The projection reference 
point is between the front and back planes. 

Ignoring function. The projection reference 
point cannot be positioned on the view plane. 

Ignoring function. The back plane is in front of 
the front plane. 

Warning. Ignoring structures that do not exist. 

Ignoring function. The specified structure does 
not exist. 

Ignoring function. The specified element does 
not exist. 

Ignoring function. Specified starting path not 
found in CSS. 
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204 



Symbolic Name 
PECEILRNG 



205 PENOLABEL 



206 PENOLABELS 



207 


PEPATHDEPNEG 


208 


PEDISPRSRNG 


250 


PENOINDEV 


251 


PENOTREQUEST 


252 


PENOTSAMPLE 


253 


PEBADPET 


254 


PEBADEGHO 


255 


PENOPETWS 


256 


PEINQOVFL 


257 


PENOQOVFL 


258 


PEINQOVFLWSCI 


259 


PEBADGLASS 


260 


PEBADDATA 


261 


PEBADIVAL 



Description 

Ignoring function. Specified search ceiling in- 
dex out of range. 

Ignoring function. The label does not exist in 
the open structure between the element pointer 
and the end of the structure. 

Ignoring function. One or both of the labels 
does not exist in the open structure between the 
element pointer and the end of the structure. 

Ignoring function. The specified path depth is 
less than 0. 

Ignoring function. The display priority is out of 
range. 

Ignoring function. The specified device is not 
available on the specified workstation. 

Ignoring function. The function requires the 
input device to be in REQUEST mode. 

Ignoring function. The function requires the 
input device to be in SAMPLE mode. 

Warning. The specified prompt/echo type is 
not available on the specified workstation. 
Prompt/echo type 1 will be used in its place. 

Ignoring function. Invalid echo area/volume. 
XMIN > XMAX, YMIN > YMAX, or ZMIN > 
ZMAX. 

Ignoring function. One of the echo area/ 
volume boundary points is outside the range of 
the device. 

Warning. One input queue has overflowed. 

Ignoring function. Input queue has not over- 
flowed. 

Warning. Input queue has overflowed, but 
associated workstation has been closed. 

Ignoring function. The input device class of the 
current input report does not match the class 
being requested. 

Ignoring function. One of the fields within the 
input device data record is in error. 

Ignoring function. Initial value is invalid. 



C 
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262 PEPTSGTBUF 

263 PELENGTBUF 

300 PERESERVE 

301 PEBDLNGTH 

302 PENOITEM 

303 PEITMINV 

304 PEBATITM 

305 PEBADCNTS 

306 PEBDMXDR 

307 PEINTERPT 
350 PEESCAPE 



351 PEESCDAT 



400 PENOAROPN 



401 PEMAXAR 



402 PEARIDINUSE 



403 PEBADARFILE 



404 PENOTOPNAR 



405 PECONFL1CT 



Description 

Ignoring function. Number of points in the ini- 
tial stroke is greater than the buffer size. 

Ignoring function. Length of the initial string is 
greater than the buffer size. 

Ignoring function. Item type is not allowed for 
user items. 

Ignoring function. Item length is invalid. 

Ignoring function. No item is left in Metafile 
input. 

Ignoring function. Metafile item is invalid. 

Ignoring function. Item type is unknown. 

Ignoring function. Content of item data record 
is invalid for the specified item type. 

Ignoring function. Maximum item data record 
length is invalid. 

Ignoring function. User item cannot be 
interpreted. 

Warning. The specified escape is not available 
on one or more workstations in this implemen- 
tation. The escape will be processed by those 
workstations on which it is available. 

Ignoring function. One of the fields within the 
escape data record is in error. 

Ignoring function. The archive file cannot be 
opened. 

Ignoring function. Opening this archive file 
would exceed the maximum number of simul- 
taneously open archive files. 

Ignoring function. Archive file identifier 
already in use. 

Ignoring function. The archive file is not a 
PHIGS archive file. 

Ignoring function. The specified archive file is 
not open. 

Ignoring function. Name conflict occurred 
while conflict resolution flag has value 
ABANDON. 
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406 PEARFULL 

407 PESTRUCTAR 

408 PEARSTRUCT 

450 PEBADERRFILE 

500 PESMALLORDER 

501 PECTLPOINTS 

502 PEBADORDER 

503 PEKNOTDECR 

504 PEINVALVIND 

505 PEDEGENFAS 

506 PEPARAMRANGE 

900 PEOVFLPH 

901 PEOVFLCSS 

902 PEIOREAD 

903 PEIOWRITE 

904 PESENDWS 

905 PERECVWS 

906 PELIBMAN 

907 PERDWSDT 

908 PEARITH 



Description 

Warning. The archive file is full. Any struc- 
tures that were archived were archived in total 

Warning. Some of the specified structures do 
not exist on the archive file. 

Warning. Some of the specified structures do 
not exist on the archive file. PHIGS will create 
empty structures in their places. 

Ignoring function. The specified error file is 
invalid. 

Ignoring function. The specified order is less 
than 1. 

Ignoring function. Not enough control points 
for specified order. 

Ignoring function. The specified order is 
inconsistent with number of knots and control 
points. 

Ignoring function. The knot sequence is not 
non-decreasing. 

Ignoring function. One or more of the vertex 
indices is out of range. 

Warning. The fill area is degenerate. 

Ignoring function. Parameter range is inconsis- 
tent with the knots. 

Storage overflow has occurred in PHIGS. 

Storage overflow has occurred in CSS. 

Input/Output error has occurred while reading. 

Input/Output error has occurred while writing. 

Input/Output error has occurred while sending 
data to a workstation. 

Input/Output error has occurred while 
receiving data from a workstation. 

Input/Output error has occurred during 
program library management. 

Input/Output error has occurred while reading 
workstation description table. 

Arithmetic error has occurred. 



C 
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2200 PEBUFSPAC 

2201 PEOUTRANG 

2000 PEFTN2000 

2001 PEFTN2001 

2002 PEFTN2002 

2003 PEFTN2003 

2004 PEFTN2004 

2005 PEFTN2005 

2006 PEFTN2006 



Description 

Buffer overflow in input or inquiry function. 

Start index out of range. 

Ignoring function. Enumeration type out of 
range. 

Ignoring function. Output parameter size 
insufficient. 

Ignoring function. List or set element not 
available. 

Ignoring function. Invalid data record. 

Ignoring function. Input parameter size out of 
range. 

Ignoring function. Invalid list of point lists. 

Ignoring function. Invalid list of filters. 
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PHIGS Tables 


PHIGS Description Table 


Data Tvoe Abbreviations 


I 


Integer 


E 


Enumeration Type 


L(type) 


List of Values of a Given Type 


MCV 


Modelling Clipping Volume 


P3 


3D Point 


R 


Real 


SET(NM) 


Set of Eligible Names 


V2/V3 


2D/3D Vector 


W 


Workstation Type 


n/s 


Not Supported 


Descriotion 


Table Entrv 



c 



number of available workstation types 

list of available workstation types 

maximum number of simultaneously open 
workstations 

maximum number of simultaneously open archive 
files 

number of available names for name sets 

number of available character sets 

character set 

maximum length of normal filter list for ISS 

maximum length of inverted filter list for ISS 

polyline index 

linetype 

linewidth scale factor 

polyline colour index 

linetype ASF 

linewidth scale factor ASF 

polyline colour index ASF 



Data Type Default or 
Initial Value 



I 

L(W) 

I 



1 

See table 1-1 



14 



( 



I 





I 


64 


I 


1 


I 





I 


n/s 


I 


n/s 


I 


1 


I 


1 


R 


1.0 


I 


1 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 



( 
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polymarker index 

marker type 

marker size scale factor 

polymarker colour index 

marker type ASF 

marker size scale factor ASF 

polymarker colour index ASF 

text index 

text font 

text precision 

character expansion factor 

character spacing 

text colour index 

text font ASF 

text precision ASF 

character expansion factor ASF 

character spacing ASF 

text colour index ASF 

character height 

character up vector 

character width 

character base vector 

text path 

text alignment (horizontal & vertical) 

annotation text character height 
annotation text character up vector 
annotation text character width 
annotation text character base vector 



Data Type 


Default or 
Initial Value 


I 


1 


I 


3 


R 


1.0 


I 


1 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


I 


1 


I 


1 (Monospaced 
Roman Simplex) 


E 


STROKE 


R 


1.0 


R 


0.0 


I 


1 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


R 


0.01 


V2 


(0.0,1.0) 


R 


n/s 


V2 


n/s 


E 


RIGHT 


2xE 


(NORMAL, 
NORMAL) 


R 


0.01 


V2 


(0.0,1.0) 


R 


n/s 


V2 


n/s 
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annotation text path 

annotation text alignment (horizontal & vertical) 

annotation style 

interior index 

interior style 

interior style index 

interior colour index 

interior style ASF 

interior style index ASF 

interior colour index ASF 

edge index 

edge flag 

edgetype 

edgewidth scale factor 

edge colour index 

edge flag ASF 

edgetype ASF 

edgewidth scale factor ASF 

edge colour index ASF 

pattern size 

pattern reference point 

pattern reference vectors 

pick identifier 

view index 

HLHSR identifier 

name set 

global modelling transformation 
local modelling transformation 



Data Tvue 


Default or 
Initial Value 


E 


RIGHT 


2xE 


(NORMAL, 
NORMAL) 


I 


1 (unconnected) 


I 


1 


E 


HOLLOW 


I 


1 


I 


1 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


I 


1 


E 


OFF 


I 


1 


R 


1.0 


I 


1 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


2xR 


n/s 


P3 


n/s 


2xV3 


n/s 


I 





I 





I 





SET(NM) 


no classes 
(empty set) 


4x4xR 


Identity 


4x4xR 


Identity 



c 
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modelling clipping volume 

modelling clipping indicator 

number of available generalized structure elements 

maximum number of distinct planes in modelling 
clipping volumes 

number of available modelling clipping operators 

list of available modelling clipping operators 



Data Tvoe 


Default or 
Initial Value 


MCV 


n/s 


E 


NOCLIP 


I 





I 





I 







empty 
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PHIGS PLUS Description Table 






Data Tvoe Abbreviations 






I Integer 






E Enumeration Type 






GCOLR General Colour 






L(type) List of Values of a Given Type 






MCV Modelling Clipping Volume 






P3 3D Point 






R Real 






SET(NM) Set of Eligible Names 






V2/V3 2D/3D Vector 






W Workstation Type 






n/s Not Supported 






Description Table Entrv 


Data Type 


Default or 
Initial Value 


polyline colour 


GCOLR 


(RGB,WHITE) 


polyline shading method 


I 


l(NONE) 


polyline shading method ASF 


E 


INDIVIDUAL 


polymarker colour 


GCOLR 


(RGB,WHITE) 


text colour 


GCOLR 


(RGB, WHITE) 


face distinguishing mode 


E 


NONE 


face culling mode 


E 


NONE 


interior colour 


GCOLR 


(RGB, WHITE) 


interior shading method 


I 


l(NONE) 


ambient reflection coefficient 


R 


1.0 


diffuse reflection coefficient 


R 


1.0 


specular reflection coefficient 


R 


1.0 


specular colour 


GCOLR 


(RGB,WHITE) 


specular exponent 


R 


0.0 


reflectance characteristics 


I 


l(NONE) 


interior shading method ASF 


E 


INDIVIDUAL 


reflectance properties ASF 


E 


INDIVIDUAL 


reflectance characteristics ASF 


E 


INDIVIDUAL 



c 



c 



c 
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back interior style 

back interior style index 

back interior colour 

back interior shading method 

back ambient reflection coefficient 

back diffuse reflection coefficient 

back specular reflection coefficient 

back specular colour 

back specular exponent 

back reflectance characteristics 

back interior style ASF 

back interior style index ASF 

back interior colour ASF 

back interior shading method ASF 

back reflectance properties ASF 

back reflectance characteristics ASF 

light source state 

edge colour 

curve approximation criteria type 

curve approximation criteria value 

curve approximation criteria ASF 

surface approximation criteria type 

surface approximation criteria value 

surface approximation criteria ASF 

rendering colour model 

depth cue index 

colour mapping index 



Data Tvoe 


Default or 




Initial Value 


E 


HOLLOW 


I 


1 


GCOLR 


(RGB,WHITE) 


I 


l(NONE) 


R 


1.0 


R 


1.0 


R 


1.0 


GCOLR 


(RGB,WHITE) 


R 


0.0 


I 


l(NONE) 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


E 


INDIVIDUAL 


L(I) 


empty 


GCOLR 


(RGB,WHITE) 


I 


Oorn/s 


R 


Oorn/s 


E 


INDIVIDUAL 


I 


n/s 


2xR 


n/s 


E 


n/s 


I 


n/s 


I 





I 


n/s 
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PHIGS Workstation Description Table 






Data Tvoe Abbreviations 






B Bounding Range 






CC Chromaticity Coefficient 






D Data Record 






E Enumeration Type 






FP Font/Precision Pair 






I Integer 






L(type) List of values of a given type 






P3 3D Point 






R Real 






n/s Not Supported 






Workstation Description Table Entrv 


Data Tvoe 


Initial Value 


workstation type 


W 


See table 1-1 


workstation category 


E 


See table 1-1 


device coordinate units 


E 


OTHER 


maximum display space size: 






in device coordinates 


3xR 


(1.0,1.0,1.0) 


in device address units 


3x1 


(1280,1024, 

24 z-buffer planes) 


number of available HLHSR identifiers 


I 


2 


list of available HLHSR identifiers 


L(I) 


NONE,ZBUFF 


number of available HLHSR modes 


I 


2 


list of available HLHSR modes 


L(I) 


NONE,ZBUFF 


number of predefined view indices 






(representations) 


I 


6 


table of predefined view representations: 






view orientation matrix 


4x4xR 


Identity 


view mapping matrix 


4x4xR 


Identity 


view clipping limits 


3xB 


(0,1,0,1,0,1) 


x-y clipping indicator 


E 


CLIP 


back clipping indicator 


E 


CLIP 


front clipping indicator 


E 


CLIP 



c 



( 



c 
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Workstation Description Table Entry 


Data Tvoe 


Initial Value 


workstation classification 


E 


RASTER 


dynamic modification accepted for: 






view representation 


E 


IRG 


polyline bundle representation 


E 


IRG 


polymarker bundle representation 


E 


IRG 


text bundle representation 


E 


IRG 


interior bundle representation 


E 


IRG 


edge bundle representation 


E 


IRG 


pattern representation 


E 


IRG 


colour representation 


E 


IRG 


workstation transformation 


E 


IRG 


highlighting filter 


E 


IRG 


invisibility filter 


E 


IRG 


HLHSR mode 


E 


IRG 


default value for deferral state: 






deferral mode 


E 


ASAP 


modification mode 


E 


NIVE 


number of available linetypes 


L(I) 


See table 1-2 


number of available linewidths 


I 


1 


nominal linewidth 


R 


1.0 (pixel) 


minimum linewidth 


R 


1.0 


maximum linewidth 


R 


1.0 


number of predefined polyline indices (bundles) 


I 


5 


table of predefined polyline bundles 




See table 1-3 


number of available marker types 


I 


8 


list of available marker types 


L(I) 


See table 1-4 


number of available marker sizes 


I 


(continuous) 


nominal marker size 


R 


1.0 (9 pixels) 


minimum marker size 


R 





maximum marker size 


R 


unlimited 
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Workstation Description Table Entry 

number of predefined polymarker indices 
(bundles) 

table of predefined polymarker bundles 

number of text font and precision pairs 

list of text font and precision pairs 

number of available character expansion factors 

minimum character expansion factor 

maximum character expansion factor 

number of available character heights 

minimum character height 

maximum character height 

number of predefined text indices (bundles) 

table of predefined text bundles 

number of available annotation styles 

list of available annotation styles 

number of available interior styles 

list of available interior styles 

number of available hatch styles 

list of available hatch styles 

number of predefined interior indices (bundles) 

table of predefined interior bundles 

number of available edgetypes 

list of available edgetypes 

number of available edgewidths 

nominal edgewidth 

minimum edgewidth 

maximum edgewidth 

number of predefined edge indices (bundles) 

table of predefined edge bundles 

number of predefined pattern indices 
(representations) 



Data Tvoe 


Initial Value 


I 


5 




See table 1-5 


I 


2 


L(FP) 


See table 1-6 


I 


(continuous) 


R 


0.0 


R 


unlimited 


I 


(continuous) 


R 


0.0 


R 


unlimited 


I 


6 




See table 1-7 


I 


2 


L(I) 


See table 1-12 


I 


3 


L(E) 


See table 1-8 


I 





L(I) 


empty 


I 


5 




See table 1-9 


I 


4 


L(I) 


See table 1-2 


I 


1 


R 


1.0 (pixel) 


R 


1.0 


R 


1.0 


I 


5 




See table 1-10 



c 



c 



c 
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Workstation Descriotion Table Entrv 


Data Tvoe 


Initial Value 


table of predefined pattern representations 




empty 


number of available colour models 


I 


2 


list of available colour models 


L(I) 


1 (RGB) 


default colour model 


I 


1 (RGB) 


colour available 


E 


COLOUR 


number of predefined colour indices 
(representations) 


I 


8 


table of predefined colour representations 




See table 1-11 


number of available generalized drawing 
primitives 3 (GDP3) 


I 





list of available generalized drawing primitives 3 
(GDP3) 




empty 


number of available generalized drawing 
primitives (GDP) 


I 





list of available generalized drawing primitives 
(GDP) 




empty 


number of display priorities supported 


I 


(unlimited) 


maximum number of polyline bundle table entries 


I 


20 


maximum number of polymarker bundle table 
entries 


I 


20 


maximum number of text bundle table entries 


I 


20 


maximum number of interior bundle table entries 


I 


20 


maximum number of edge bundle table entries 


I 


20 


maximum number of pattern table entries 


I 





maximum number of colour indices 


I 


256 


maximum number of view indices 


I 


20 


dynamic modification accepted for: 






structure content modification 


E 


IRG 


post structure 


E 


IRG 


unpost structure 


E 


ERG 


delete structure 


E 


IRG 


reference modification 


E 


IRG 
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Workstation Description Table Entry 

number of logical devices of class LOCATOR 

number of logical input devices of class STROKE 

number of logical input devices of class 
VALUATOR 

number of logical devices of class CHOICE 

number of logical input devices of class PICK 

number of logical input devices of class STRING 



Data Type 



Initial Value 











c 



( 



c 
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PHIGS PLUS Workstation Description Table 






Data Tvoe Abbreviations 






B Bounding Range 






CC Chromaticity Coefficient 






D Data Record 






E Enumeration Type 






FP Font/Precision Pair 






I Integer 






L(type) List of values of a given type 






P3 3D Point 






R Real 






n/s Not Supported 






Workstation Description Table Entrv 


Data Tvoe 


Initial Value 


number of available directly specifiable 






colour models 


I 


1 (RGB) 


list of available directly specifiable color models 


I 


1 (RGB) 


number of available rendering colour models 


I 


1 (RGB) 


list of available rendering colour models 


I 


1 (RGB) 


dynamic modification accepted for: 






data mapping representation 


E 


IRG 


reflectance representation 


E 


IRG 


parametric surface representation 


E 


IRG 


light source representation 


E 


IRG 


depth cue representation 


E 


IRG 


colour mapping representation 


E 


IRG 


table of predefined polyline bundles 




See table 1-3 


table of predefined polymarker bundles 




See table 1-5 


table of predefined text bundles 




See table 1-7 


table of predefined interior bundles 




See table 1-9 


table of predefined edge bundles 




See table 1-10 


maximum number of data mapping bundle table 






entries 


I 


n/s 


number of predefined data mapping bundles 


I 


n/s 



ESV Workstation Reference Manual [2.0] 



1 -107 



ES/PEX 



Workstation Description Table Entry 

maximum number of reflectance bundle table 
entries 

number of predefined reflectance bundles 

for every entry: 

reflectance index 

reflectance characteristics 

ambient reflection coefficient 

diffuse reflection coefficient 

specular reflection coefficient 

specular colour 

specular exponent 

maximum number of parametric surface bundle 
table entries 

number of predefined parametric surface bundles 

number of predefined pattern representations 

maximum number of light source table entries 

number of predefined light source table indices 

table of predefined light sources 

maximum number of depth cue table entries 

number of predefined depth cue indices 

table of predefined depth cue representations 

maximum number of colour mapping table entries I 

number of predefined colour mapping table 
entries 

table of predefined colour mappings 

number of available polyline shading models 

list of available polyline shading methods 

number of available interior styles 

number of available data mapping methods 

list of available data mapping methods 

number of available interior shading methods 



Data Tvoe 


Initial Value 


I 


20 


I 


1 


I 


1 


I 


1 


R 


1.0 


R 


1.0 


R 


1.0 


GCOLR 


1 


R 


1.0 


I 


n/s 


I 


n/s 


I 





I 


12 


I 


1 




See table 1-18 


I 


6 


I 


2 




See table 1-17 


I 


n/s 


I 


0(n/s) 




n/s 


I 


2 




See table 1-13 




See table 1-8 


I 


n/s 


L(I) 


n/s 


I 


2 



c 



( 
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Workstation Description Table Entry 

list of available interior shading methods 

number of available reflectance characteristics 

values 

list of available reflectance characteristics 

maximum non-uniform B-spline curve order 

maximum trimming curve order 

number of available curve approximation 
criteria types 

list of available curve approximation 
criteria types 

maximum non-uniform b-spline surface order 

number of available surface approximation 
criteria types 

list of available surface approximation 
criteria types 

number of available trimming curve approximation 
criteria types 

list of available trimming curve approximation 
criteria types 

number of available parametric surface 
characteristics types 

list of available parametric surface 
characteristics types 

number of available light source types 

list of available light source types 

maximum number of simultaneously active 
non-ambient light sources 

number of available colour mapping methods 

list of available colour mapping methods 

number of available true colours 

maximum number of pseudo colour entries 



Data Tvoe 


Initial Value 


L(I) 


See table 1-14 


I 


4 




See table 1-16 


I 


n/s 


I 


0(n/s) 



I 



L(I) 


n/s 


I 


(n/s) 


I 





L(I) 


n/s 


I 





L(I) 


n/s 


I 


n/s 


L(I) 


n/s 


I 


4 




See table 1-15 


I 


12 


I 


n/s 


L(I) 


n/s 


I 


2 24 


I 


n/s 
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Table 1-1. Workstation type and category 

Type CName Category 

X drawable phigs_ws_type_x_drawable OUTPUT 

X tool phigs_wsJype_x_tool OUTIN 



c 



Table 1-2. Available line and/or edge types 

Type 

1 
2 
3 
4 PLINE DOT DASH Dot-dashed 



CName 


Meaning 


PLINE__SOLID 


Solid 


PLINEJ)ASH 


Dashed 


PLINE DOT 


Dotted 



Table 1-3. Predefined extendedf polyline bundle table 



Bundle 
Index 



Linetype 



Line Width 
Scale Factor 



Colour 
Index t 

1 



Shading 
Methodf 

None 



Approx. 
Type t 

N/A 



1 Solid 1.0 

f PHIGS PLUS extension. 

$ Predefined Extended Polymarker Bundle entries use colour model INDIRECT. 



A pprox. 
Value f 

N/A 





Table 1-4. Available marker types 




Value 


CName 


Meaning 


1 


PMARKER_DOT 


Point 


2 


PMARKER_PLUS 


Plus 


3 


PMARKER_ ASTERISK 


Asterisk 


4 


PMARKER CIRCLE 


Circle 


5 


PMARKER_CROSS 


Cross 





PES_MARKER_DEF_STAR 


Asterisk 


-1 


PESJ/IARKER_DIAMOND 


Diamond 


-2 


PES„MARKER_FAST_DOT 


Fast Dot 


-3 


PES_MARKER_TRIANGLE 


Triangle 


-4 


PES_MARKER__SQUARE 


Square 


-5 


PESJVIARKERJNVJTRIANGLE 


Inverted Triangle 


-6 


PES^MARKER^OCTAGON 


Octagon 



c 



c 
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Table 1-5. Predefined polymarker bundle table 

Bundle Marker Marker Size Colour 

Index Type Scale Factor Index t 

1 Asterisk 1.0 1 

t All Predefined Extended Polymarker Bundle entries (PHIGS PLUS extension) use colour 
model INDIRECT. 

Table 1-6. Available text fonts and precisions 

Font Number CName Precisions Supported 

1 PFONT_MONO STROKE 

2 PFONT_COMPLEX STROKE 

Table 1-7. Predefined extended text bundle table 

Bundle Font Text Expansion Character Colour 

Index Number Precision Factor Spacing Index t 

1 1 STROKE 1.0 0.0 1 

t All Predefined Extended Polymarker Bundle entries (PHIGS PLUS extension) use colour 
model INDIRECT. 

Table 1-8. Available interior styles 

CName Meaning 

PSTYLE_HOLLOW Hollow 
PSTYLE_SOLID Solid-filled 
PSTYLEJEMPTY Empty 

Table 1-9. Predefined fill area interior bundle table 



Bundle 


Interior 


Interior 


Colour 


Reflectance 


Shading 


Index 


Stvle 


Stvle Index 


Index 


Equationt 


Method 


1 


Hollow 


1 


1 


None 


None 



t All Predefined Extended Edge Bundle entries (PHIGS PLUS extension) use colour model 
INDIRECT; have back attribute values identical to the front; and have the following area 
properties: 

Ambient Diffuse Specular Specular Specular Transparency 

Coefficient Coefficient Coefficient Colour Exponent Coefficient 

1.0 1.0 1.0 (RGB,1.0,1.0,1.0) 0.0 0.0 
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Table 1-10. Predefined edge bundle table £ 

Bundle Edge Edgetvpe Edeewidth Colour 

Index Flag Scale Factor Index f 

1 OFF Solid 1.0 1 

t All Predefined Extended Edge Bundle entries (PHIGS PLUS extension) use colour model 
INDIRECT. 



Table 1-11. Pre 


defined 


colour table 




Colour Index Red 


Green 


Blue 


Description 


0.0 


0.0 


0.0 


Black 


1 1.0 


1.0 


1.0 


White 


2 1.0 


0.0 


0.0 


Red 


3 0.0 


1.0 


0.0 


Green 


4 0.0 


0.0 


1.0 


Blue 


5 1.0 


1.0 


0.0 


Yellow 


6 0.0 


1.0 


1.0 


Cyan 


7 1.0 


0.0 


1.0 


Magenta 


Table 1-12. Available annotation styles 




Value C Name 






Meaning 


1 PANNO STYLE UNCONNECTED 


Unconnected 


2 PANNO 


STYLE 


LEAD LINE 


Lead Line 



Table 1-13. Polyline shading methods 

Value CName Meaning 

1 PSD_NONE No Shading 

2 PSD_COLOUR Colour Shading 

Table 1-14. Available interior shading methods 

Value CName Meaning 

1 PSD_NON£ No Shading 

2 PSD_COLOUR Colour Shading 



c 
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Table 1-15. Available light source types 

Value CName Meaning 

1 PLIGHT_AMBIENT Ambient Light Source 

2 PLIGHT_DIRECTIONAL Directional Light Source 

3 PLIGHT_POSITIONAL Positional Light Source 

4 PLIGHT_SPOT Spot Light Source 

Table 1-16. Available reflectance characteristics 



Value 

1 

2 
3 
4 



CName 

PREFL__NONE 
PREFL_AMBIENT 
PREFL_AMB_DIFF 
PREFL AMB DIFF SPEC 



Meaning 

No Reflectance Calculation Performed 

Use Ambient Term 

Use Ambient and Diffuse Terms 

Use Ambient, Diffuse, and Specular Terms 



Table 1-17. Predefined depth cue table 

Depth Cue De pth Cue De pth Cue Depth Cue De pth Cue 

Index Mode Reference Planes Scale Factors Colour 

SUPPRESSED (1.0,0.0) (1.0,1.0) (INDIRECT,0) 

1 ALLOWED (1.0,0.0) (1.0,0.02) (INDIRECT,0) 

Table 1-18. Predefined light sources 

Index Type Data Record 

1 DIRECTIONAL (RGB ,1.0,1 .0, 1 .0),0.0,0.0, 1 .0 
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C and FORTRAN Bindings f 

The following tables list the C and FORTRAN bindings for the PHIGS and 
PHIGS PLUS/PEX functions. 

In the PHIGS table, an asterisk (*) means the function is a C binding 
function, and a dagger (f ) means the function is a FORTRAN binding 
function. The C and FORTRAN bindings both split the 
INQUIRE HLHSR FACILITIES function into the following two functions: 

INQUIRE HLHSR IDENTIFIER FACILITIES 

INQUIRE HLHSR MODE FACILITIES 

In the PHIGS PLUS table, the C binding names are from the ISO PHIGS 
PLUS working draft. Since the FORTRAN bindings are not yet defined as a 
standard, the names listed in this table are our attempt to anticipate what they 
will be. The functions shown in bold typeface are defined correctly in 
PEX-SI beta and will probably remain the same in the release to MIT. The 
functions shown in italics are those whose function and/or C binding name 
differ in the PEX-SI beta but are expected to be corrected in the release to 
MIT. The functions shown in regular font indicate those implemented in 
PEX-SI via an older function name that is not in the PHIGS PLUS Dp and will 
probably remain in the release to MIT. 



C 



C 
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Example Programs 



The example programs are provided as working ES/PEX programs. The pro- 
grams may be found in the following directory on the distribution tape: 
/usr/people/fstest/demo/pexexamples. 

The programs demonstrate the minimal amount of coding necessary to 
perform the functions stated within each program. Care has been taken to 
demonstrate a "proper" coding style to ensure that these programs may be 
used with other, larger models. There are many methods used in the example 
programs that are strictly a reflection of the authors' style. There is no "one 
way" to write ES/PEX programs; however, these example programs represent 
one way to demonstrate the basic functionality. 

There are four programs implemented in two different ways. One way 
uses the Xlib calls and the other way uses the Motif Graphical User Interface. 
examplel .c through example4.c use the Xlib calls for the user interface. 
motif 1.c through motif4.c use the Motif Graphical User Interface. 

Both sets of programs link with the same PHIGS procedures (phigsl.c 
through phlgs4.c). Therefore, the PHIGS functionality is identical; only the 
user interface is different. This is done to demonstrate the different program- 
ming environments between Xlib calls and Motif calls. 

The PHIGS functionality in the example programs progresses from a very 
simple program (1), which displays two objects and exits, to a fully interac- 
tive program (4) which demonstrates the use of the dials device along with 
picking on 3D objects. 

Users should become familiar with what the example programs do before 
"pasting" them into other applications. Many hours of frustration may be 
avoided by taking time to understand the reasoning behind the implementa- 
tion of these example programs. 
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Makefile 

CCOPT = -systype bsd43 
CDEBUG = -g 

DEFNS = -Wf,-XNp50000 -Wf , -XNd5 

CFLAGS = $ (CDEBUG) $ (CCOPT) $ (DEFNS) -I/bsd43/usr/include/XllR3 
LDFLAGS = $ (CDEBUG) $ (CCOPT) 
FIN = -lm -lc /usr/lib/libc.a 



# ——-—_. . . _________ . „. . . __ _ 

# Variables specific to clients created by this Makefile - edit as needed 

OBJS1 = motif 1 .o 

LIBS1 = -IPEXapi -iXm -iXt -1X11 

0BJS2 = phigs2.o motif 2. o 

LIBS2 = -IPEXapi -IXm -IXt -IXinput -IXext -1X11 

0BJS3 = phigs3.o motif 3. o 

LIBS3 = -IPEXapi -IXm -IXt -IXinput -IXext -1X11 

0BJS4 = phigs4.o motif 4. o 

LIBS4 = -IPEXapi -IXm -IXt -IXinput -lXpick -IXext -1X11 

XOBJS1 = examplel.o 

XLIBS1 = -IPEXapi -1X11 

X0BJS2 = phigs2.o example2.o 

XLIBS2 = -IPEXapi -1X11 

X0BJS3 = phigs3.o example3.o 

XLIBS3 = -IPEXapi -IXinput -IXext -1X11 

X0BJS4 = phigs4.o example 4. o 

XLIBS4 = -IPEXapi -IXinput -lXpick -IXext -1X11 

ALL = motifl mot if 2 mot if 3 mot if 4 examplel example2 example3 example4 

# .—____-___ __ „___„ ___ 

# Commands specific to clients created by this Makefile - edit as needed 

all: $(ALL) 

clean: 

rm -f *.o $ (ALL) 

motifl: $(0BJS1) 

$(CC) $ (LDFLAGS) -o motifl $(0BJS1) $(LIBS1) $ (FIN) f 
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motif 2: $(OBJS2) 

$(CC) $(LDFLAGS) -o motif 2 $(0BJS2) $(LIBS2) $ (FIN) 

motif 3: $(0BJS3) 

$(CC) $(LDFLAGS) -o motif 3 $ (0BJS3) $ (LIBS3) $ (FIN) 

motif 4: $(0BJS4) 

$(CC) $(LDFLAGS) -o motif 4 $ (0BJS4) $(LIBS4) $ (FIN) 

example 1 : $ (X0BJS1) 

$(CC) $(LDFLAGS) -oexamplel $(X0BJS1) $(XLIBS1) $ (FIN) 

example2 : $ (X0BJS2 ) 

$(CC) $(LDFLAGS) -o example2 $(X0BJS2) $(XLIBS2) $ (FIN) 

example3 : $ (X0BJS3) 

$(CC) $(LDFLAGS) -o example3 $(X0BJS3) $(XLIBS3) $ (FIN) 

example 4 : $ (X0BJS4) 

$(CC) $(LDFLAGS) -oexample4 $(X0BJS4) $(XLIBS4) $ (FIN) 
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example"! .c 

/* 



example 1 . c 



This program defines and displays two squares on the open 
PEX workstation. One square is a 2d polyline object and the 
other is a 2d fillarea object. 

This program shows the minimum PEX calls required to display 
simple objects. System defaults are used and there is no 
event handling. 

Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990, Evans & Sutherland 



"/ 



#include <X11/Xlib.h> 
#include <Xll/Xatom.h> 
#include <Xll/phigs/phigs .h> 

#define POLYSQUARE 1 
#define FILLSQUARE 2 
#define DISPLAY STRUCT 3 



/* Include Xlib definitions */ 
/* Include Phigs/Phigs+ extensions */ 
/* Define Structure name constants */ 



#define WS 


1 


#define WINPOSX 


100 


#define WINPOSY 


100 


#define WINWIDTH 


600 


#define WINHEIGHT 


600 


Window myWin; 




Display *dpy; 




main() 




I 

char *display = 


NULL; 



/* Workstation ID number 



"7 



if ( ! (dpy = XOpenDisplay (display) ) ) /* Attempt to open the display */ 
{ 

perror ("Cannot open display\n") ; 
exit (-1) ; 
} 



C 



( 



c 
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/* Create a simple, unmapped input /output window */ 
myWin = XCreateSimpleWindow (dpy, RootWindow (dpy, Def aultScreen (dpy) ) , 
WINPOSX, WINPOSY, WINWIDTH, WINHEIGHT, 0, NULL, NULL); 
/* Change the window name property */ 
XChangeProperty(dpy, myWin, XA_WM_NAME, XA_STRING, 8, 

PropModeReplace, "Example 1: PHIGS Squares", 26); 
/* Map the window for display */ 
XMapWindow(dpy, myWin) ; 



/* Begin PHIGS calls 
StartPhigs (dpy, myWin) ; 



"/ 



StartPhigs 

This routine is the top level routine that calls all supporting 
routines in the logical order of a usual phigs routine i.e. 
open PEX, setup the workstation parameters and define the phigs 
structure. 



*/ 



StartPhigs (dpy, win) 
Display *dpy; 
Window win; 
{ 

OpenPex(dpy) ; 

SetupWorkstation (dpy, win), 

Make_squares () ; 

sleep (5) ; 

pclose_ws (WS) ; 

pclose_j?higs () ; 



/* Routine to start phigs calls */ 



Open PEX */ 

Setup PHIGS Workstation parameters */ 



/* Create Phigs structures */ 

/* Display structures for 5 seconds */ 

/* Close workstation */ 

/* Close PHIGS */ 



OpenPex 

This routine Opens PEX on the display that was passed 
as an argument . 

*/ 

OpenPex (dpy) 
Display *dpy; 
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{ 

Pxphigs_info xinfo; 
unsigned long infomask; 

xinfo. display = dpy; 
xinfo. rmdb = NULL; 
xinfo.appl__id.name = NULL; 
xinfo. appl_id. class = NULL; 
xinfo. args .argc__p = NULL; 
xinfo. args .argv = NULL; 
xinfo. flags .no_monitor = 1; 
xinfo. flags .force_client_SS = 0; 

infomask = PXPHIGS_INFO_DISPLAY | PXPHIGS_INFO_FLAGS_NO_MON; 

/* Open Pex */ 

popen_xphigs ( (char*) NULL, PDEF_MEM_SIZE, infomask, &xinf o) ; 
} 

/* 

SetupWorkstation 

This routine opens a PHIGS workstation and sets the structure edit mode 
to insert elements. The update state is also set to PWAIT causing the 
workstation display to be updated only upon request. 

*/ 

SetupWorkstation (dpy, win) 
Display *dpy; 
Window win; 
{ 

Pconnid_x_drawable conn; 

conn. display = dpy; 
conn .drawable_id = win; 
popen_ws(WS, (Pconnid *) (Sconn) , phigs_ws_type_x_drawable) ; /*0pen WS*/ 

pset_edit_mode (PEDIT_INSERT) ; /* Set edit mode to insert elements */ 

/* Set update state to WAIT */ 
pset_disp_upd_St (WS, PDEFER_WAIT, PMODE_NIVE) ; 
} 

/* 

Make_squares 
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Make_squares defines a polyline square and a fillarea square in 2 
dimensions. Structures POLYSQUARE and FILLSQUARE are defined to contain 
these data elements along with color and style attributes to be applied 
to the data elements. A higher level structure DISPLAY_STRUCT is defined 
to include both the POLYSQUARE and FILLSQUARE structures and is then 
posted to the open workstation to be displayed. 
*/ 

Make_squares () 
{ 



static Ppoint line_points [] = 

{ { 0.5, 0.5} , { 0.9, 0.5} 

{ 0.9, 0.9} , { 0.5, 0.9} 

{ 0.5, 0.5} }; 



/* Define points for line drawing */ 



static Ppoint f ill_points [] = 
{ { 0.1, 0.1} , { 0.5, 0.1} , 
{ 0.5, 0.5} , { 0.1, 0.5} }; 



/* Define points for filled drawing */ 



Ppoint_list Line_list, Fill_list; 

popen_struct (POLYSQUARE) ; /* Open line drawing structure */ 
pset_line_colr_ind(2) ; /* Assign default index color 2 to lines*/ 
Line_list.num_points =5; /* Fill in number of points in list */ 
Line_list .points = line_j?oints; /* Pointer to point array */ 

ppolyline(&Line_list) ; /* Create a polyline element */ 

pclose_struct () ; /* Close line drawing structure */ 

popen_struct (FILLSQUARE) ; /* Open filled drawing structure */ 

pset_int_style(PSTYLE_SOLID) ;/* Set interior style to be solid */ 
pset_int_colr_ind(3) ; /* Assign default index color 3 to lines*/ 

Fill_list.num_points = 4; /* Fill in number of points in list */ 

Fill_list .points = f illjpoints; /* Pointer to point array */ 

pfill_area(&Fill_list) ; /* Create a fill area element */ 

pclose_struct() ; /* Close filled drawing structure */ 

popen_struct ( DISPLAY_STRUCT ); /* Open the top level display structure */ 
pexec_struct (POLYSQUARE) ; /* Include the line drawn square */ 
pexec_struct (FILLSQUARE) ; /* Include the filled square */ 

pclose struct () ; 



ppost_struct (WS, DISPLAY_STRUCT, 1.0); 
pupd_ws (WS, PUPD_PERFORM) ; 
} 



/* Post DISPLAY_STRUCT, prio 1 */ 
/* Update the workstation */ 
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motif 1.c 

/* 



m o t i f 1 



This program creates a drawing surface via a top-level shell widget. Two 
PEX objects are then drawn on this surface and the program displays the 
image for 5 seconds before exiting. 

Author: Rich Thomson 

Date: Thursday, June 12th, 1990 

Modified J. Buckmiller Mar 1991. Approved C binding 
Copyright (C) 1990, Evans & Sutherland Computer Corporation 
*/ 

#include <X11/Xlib.h> /* Include Xlib definitions */ 

#include <Xll/phigs/phigs .h> /* Include Phigs/Phigs+ extensions */ 

#include <X11/Intrinsic .h> /* Toolkit intrinsics */ 
#include <Xm/Xm.h>/* resource names */ 

#define POLYSQUARE 1 /* Define Structure name constants */ 

#define FILLSQUARE 2 

#define DISPLAY_STRUCT 3 

tdefine WS 1 /* Workstation ID number */ 

#define WINPOSX 100 

#define WINPOSY 100 

#define WINWIDTH 600 

#define WINHEIGHT 600 

/* 
main 

The main routine creates the widget hierarchy for the program, realizes the 
hierarchy and then calls StartPhigs. The widget hierarchy used here is: 

motifl (class topLevelShell) 
The display connection (dpy) and window ID (drawWindow) of the top-level 
shell widget are available after the widget hierarchy has been realized. 

*/ 

main(argc, argv) 
int argc; 
char *argv[] ; 

{ 

register int n; 
Arg args [10] ; 
Widget topLevel; 

/* create topLevelShell widget */ 
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topLevel = Xtlnitialize ("motif l" f "Example", NULL, 0, &argc, argv) ; 

n = 0; 

XtSetArg(args[n], XmNheight, WINHEIGHT) ; n++; 

XtSetArg(args[n] , XmNwidth, WINWIDTH) ; n++; 

XtSetArg(args[n] , XmNx, WINPOSX) ; n++; 

XtSetArg(args[n] , XmNy, WINPOSY) ; n++; 

XtSetArg(args[n] , XmNtitle, "Example 1"); n++; 

XtSetValues (topLevel, args, n);/* set position and size resources */ 

XtRealizeWidget (topLevel) ; /* realize (and map) topLevel widget */ 

StartPhigs (XtDisplay (topLevel) , XtWindow (topLevel) ) ; 

/* Begin PHIGS calls */ 



/* 

StartPhigs 

This routine is the top level routine that calls all supporting routines 
in the logical order of a usual phigs routine i.e., open PEX, setup the 
workstation parameters and define the phigs structure. 
*/ 

StartPhigs (dpy, win) /* Routine to start phigs calls */ 

Display *dpy; 

Window win; 

{ 

OpenPex(dpy) ; /* Open PEX */ 

SetupWorkstation(dpy, win); /* Setup PHIGS Workstation parameters */ 
Make_squares () ; /* Create Phigs structures */ 

sleep (5); /* Display structures for 5 seconds */ 

pclose_ws (WS) ; /* Close workstation */ 

pclose_phigs () ; /* Close PHIGS */ 

} 

/* 

OpenPex 

This routine Opens PEX on the display that was passed as an argument. 

*/ 

OpenPex (dpy) 

Display *dpy; 
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Pxphigs_info xinfo; 
unsigned long infoiriask; 

xinfo. display = dpy; 
xinfo. rmdb = NULL; 
xinfo.appl_id.name = NULL; 
xinfo. appl_id. class = NULL; 
xinfo.args.argc_p = NULL; 
xinfo. args.argv = NULL; 
xinfo.f lags ,no_monitor - 1; 
xinfo.flags.force_client_SS =0; 

infomask = PXPHIGS__INFO_DISPLAY | PXPHIGS_INFO_FLAGS_NO_MON; 

/* Open Pex */ 
popen_xphigs ( (char*) NULL, PDEF_MEM_SIZE, infomask, &xinfo) ; 

} 

/* 

SetupWorkstation 

This routine opens a PHIGS workstation and sets the structure edit mode to 
insert elements. The update state is also set to PWAIT causing the 
workstation display to be updated only upon request. 

*/ 

SetupWorkstation (dpy, win) 
Display *dpy; 
Window win; 
{ 

Pconnid_x_drawable conn; 

conn. display = dpy; 
conn.drawable_id = win; 

/* Open WS */ 
popen_ws(WS, (Pconnid *) (&conn) , phigs_ws_type_x_drawable) ; 

pset_edit_mode (PEDIT_INSERT) ; /* Set edit mode to insert elements */ 
pset_disp_upd_st (WS, PDEFER_WAIT, PMODE_NIVE) ; 

/* Set update state to WAIT */ 

} 
/* 

Make_squares 

Make_squares defines a polyline square and a fillarea square in 2 
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dimensions. Structures POLYSQUARE and FILLSQUARE are defined to contain 
these data elements along with color and style attributes to be applied to 
the data elements. A higher level structure DISPLAY_STRUCT is defined to 
include both the POLYSQUARE and FILLSQUARE structures and is then posted 
to the open workstation to be displayed. 
*/ 

Make_squares () 
{ 



static Ppoint 
{ { 0.5, 0.5} 
{ 0.9, 0.9} 
{ 0.5, 0.5} 



line_j?oints [ ] = 
{ 0.9, 0.5} , 
{ 0.5, 0.9} , 



/* Define points for line drawing */ 



static Ppoint 
{ { 0.1, 0.1} 
{ 0.5, 0.5} 



filljpoints []= /* Define points for filled drawing */ 
{ 0.5, 0.1} , 
{ 0.1, 0.5} }; 



Ppoint__list Line_list, Fill_list; 

popen_struct (POLYSQUARE) ; /* Open line drawing structure */ 
pset_line_colr__ind(2) ; /* Assign default index color 2 to lines*/ 

Line_list .numjpoints = 5; /* Fill in number of points in list */ 

Line_list .points = linejoints; /* Pointer to point array */ 

ppolyline (&Line_list) ; /* Create a polyline element */ 

pclose_struct () ; /* Close line drawing structure */ 

popen_struct (FILLSQUARE) ; /* Open filled drawing structure */ 

pset_int_style(PSTYLE_SOLID) ;/* Set interior style to be solid */ 
pset_int_colr_ind(3) ; /* Assign default index color 3 to lines*/ 

Fill_list .numjpoints = 4; /* Fill in number of points in list */ 

Fill_list .points = f ill_jpoints; /* Pointer to point array */ 

pfill_area (&Fill_list) ; /* Create a fill area element */ 

pclose_struct () ; /* Close filled drawing structure */ 

popen_struct ( DISPLAY_STRUCT ); /* Open the top level display struct. */ 

pexec_struct (POLYSQUARE) ; /* Include the line drawn square */ 

pexec_struct (FILLSQUARE) ; /* Include the filled square */ 

pclose_struct () ; 

ppost_struct (WS, DISPLAY_STRUCT, 1.0); /* Post DISPLAY_STRUCT, prio 1 */ 

pupd_ws(WS, PUPD_PERFORM) ; /* Update the workstation */ 
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example2.c f^ 

/* 

example2 .c 

This program defines and displays two boxes on the open PEX workstation . 
One box is a 3d polyline object and the other is a 3d fillarea object. This 
program incorporates a PHIGS view representation. The view is set to 
encompass -1.5 to 1.5 in model space coordinates with a parallel projection 
matrix. This program shows command line arguments to handle Xlib 
environment calls as well as an event loop. To exit this program press any 
keyboard key. 

Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990, Evans & Sutherland 

*/ 

#include <X11/Xlib.h> 

#include <Xll/Xatom.h> 

#include <Xll/Xproto.h> 

#include <Xll/extensions/XInput .h> 

#include <Xll/phigs/phigs .h> /* PHIGS extensions to X */ 

#include <Xll/keysymdef .h> 

#include "header2.h" /* local includes */ 



( 



Window myWin; 

Display *dpy; 

char *ProgramName; 

Pint PEX_error; /* for PEX error number handling */ 

main(argc, argv) 
int argc; 
char *argv[] ; 
{ 

int i; 

char *geom = NULL; 

char *display = NULL; 

int winposx, winposy, winwidth, winheight; 

ProgramName = argv[0]; 

winposx =100; /* default window geometry */ ^ 
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winheight = 600; 
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for (i=l; i < argc; i++) 
{ 

char *arg = argv[i]; 



/* Parse the command line */ 



if (arg[0] == '-') 
{ 

switch (arg[l] ) 
{ 

case 'd' : 

if (++i >= argc) usage () ; 

display = argv[i]; 
continue; 
case ' q' : 

if (++i >= argc) usage () ; 

geom = argv[i] ; 
continue; 
default : 

usage () ; 



/* -display hostidpy */ 



/* -geometry hostidpy */ 



} 



} 



} 



if ( ! (dpy = XOpenDisplay (display) ) ) /* Attempt to open the display */ 
{ 

perror ("Cannot open display\n") ; 
exit(-l) ; 



if (geom) 

{ /* Generate position and size from the geometry string */ 

(void) XParseGeometry (geom, Swinposx, &winposy, Swinwidth, 
Swinheight) ; 

} 

/* Create a simple, unmapped input /output window */ 
myWin = XCreateSimpleWindow(dpy, Root Window (dpy, Def aultScreen (dpy) ) , 
winposx, winposy, winwidth, winheight, 0, NULL, NULL) ; 

/* Change the window name property */ 
XChangeProperty(dpy, myWin, XA_WM_NAME, XA_STRING, 8, 

PropModeReplace, "Example 2: Press any key to exit", 33); 
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/* Map the window for display */ 
XMapWindow(dpy, myWin) ; 

/* Begin PHIGS calls */ 

StartPhigs (dpy, myWin) ; 



/* 

usage 

This routine prints out command line argument information if the user 

supplied arguments are incorrect. 

*/ 



usage () 



fprintf (stderr, "usage: %s [-options . ..]\n\n", ProgramName) ; 

fprintf (stderr, "where options include: \n") ; 

fprintf ( stderr , " -display host: dpy X server to use\n") ; 

fprintf ( stderr , " -geometry geom geometry of window\n") ; 

fprintf (stderr, "\n") ; 

exit (1) ; 



/* 

Get_e vents 

This routine is the event handler of X events that are generated 

by the user. Only KeyPress and Expose events are handled at this time. 

*/ 

Get_e vents (dpy) 
Display *dpy; 
{ 

XEvent report; 

int done = 0; 

/* setup the event mask to return keyboard and expose events */ 
XSelectlnput (dpy, myWin, KeyPressMask | ExposureMask ); 
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while ( '.done) 
{ 
XNextEvent (dpy, &report) ; 
switch (report .type) 
{ 



/* Loop to get events 
/* Get the Event 



/* Keypress on keyboard = exit */ 



case KeyPress: 

done - 1; 

break; 
case Expose: /* Expose events = redraw */ 

predraw_all_structs(l, PFLAG_ALWAYS) ; 

break; 
default: 

break; 
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motif2.c 

/* 

m o t i f 2 . c 

This program expands on motif 1 by using a slightly more elaborate widget 
hierarchy to display the drawing area and a push button. The push button 
allows the user to specify when the program should exit. Otherwise, it is 
the same as motif 1. 

Author:. Rich Thomson 

Date: Thursday, June 12th, 1990 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990, Evans & Sutherland Computer Corporation 
*/ 

#include <X11/Xlib.h> 

#include <Xll/phigs/phigs .h> /* PHIGS extensions to X */ 

♦include <X11/Intrinsic.h>/* Toolkit intrinsics */ 

♦include <Xm/Xm.h>/* Motif declarations */ 

♦include <Xm/RowColumn.h>/* row column widget declarations */ 

♦include <Xm/DrawingA.h>/* drawing area widget declarations */ 

♦include <Xm/PushBG.h>/* push button gadget declarations */ 

♦include "header2.h" 

char *ProgramName; 

Pint PEX_error; /* for PEX error number handling */ 

Boolean done; /* end flag */ 

/* 

quit_CB 

The callback procedure for the quit pushbutton widget. It simply sets the 

event processing exit flag to True, which will cause Get_events to stop 

processing events. 

*/ 

void quit__CB ( quit But ton, client_data, call_data) 

Widget quitButton; 

caddr_t client_data; 

XmAnyCallbackStruct *call_data; 
{ 

if (call data->reason == XmCR ACTIVATE) 
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done 9= True; 

} 

/* 
drawArea_CB 

The callback procedure for the drawing area widget. It redraws all the 

structures on the workstation. 

*/ 

void drawArea_CB(drawArea f client_data f call_data) 

Widget drawArea; 

caddr_t client_data; 

XmDrawingAreaCallbackStruct *call_data ; 
{ 

if (call_data->reason == XmCR_EXPOSE) 

predraw_all_structs(WS, PFLAG_ALWAYS) ; 
} 

/* 

main 

The main routine creates the widget hierarchy for the program and then calls 
StartPhigs. StartPhigs will then call Get_events to initiate event 
processing. 

The widget hierarchy used here is : 

motif2 (class topLevelShell) 
I 

+ — rowcol (class RowColumn) 
I 

+ drawArea (class DrawingArea) 

I 

+ quit (class PushButtonGadget) 

The row column widget is used for organizing its child widgets into a 
columnar layout. The drawing area widget is used for PEX operations and the 
PEX workstation is opened on its window. A push button is used to supply a 
quit operation. 

Any necessary resources for the widgets are specified here in the program, 
which override any user defaults or command-line options. Note that this 
is not very friendly to the user who may want to change the font of the 
push buttons. A friendlier way is to provide an application defaults file 
which the user may override with user defaults or command-line arguments. 
For simplicity, I have set the arguments here directly. 
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The display connection (dpy) and window ID (drawWindow) of the drawing area m 
widget are available after the widget hierarchy has been realized. V.. 

BEWARE ! ! BEWARE ! ! 

The drawing area widget in Motif 1.0 has a bug in that it ignores 
height and width resources supplied at creation time. A workaround 
I've found is to set the margins of the drawing area to be half the 
desired height and width. Since the margins specify the boundary 
between the drawing area widget's border and any children of the 
drawing area widget (we have none here) , the drawing area widget will 
be sized to contain its children plus twice the margins in each 
direction. Hence to get a 600x600 drawing area widget, you can set the 
margins to 300. Other workarounds suggested involve creating the 
drawing area widget as a child of other widgets, but where there are 
no children of the drawing area, I prefer setting the margins. 

*/ 

main(argc, argv) 

int argc; 

char *argv[] ; 

{ 

Arg args [10] ; 

register int n; 

Widget topLevel, rowColumn, quitButton, drawArea; 

XFontStruct *buttonFont; 



( 



ProgramName = argv[0]; 

/* create topLevelShell */ 
topLevel = Xt Initialize (ProgramName, "Example", NULL, 0, &argc, argv) ; 

n = 0/ /* set the window title */ 
XtSetArg(args[n], XmNtitle, "Example 2"); n++; 
XtSetVa lues (topLevel, args, n) ; 

rowColumn = /* create row column for layout */ 

XtCreateManagedWidget ("rowcol", xmRowColumnWidgetClass, topLevel, 
NULL, 0); 

n = 0; /* create drawing area for PEX */ 
XtSetArg(args[n] , XmNmarginWidth, 300); n++; 
XtSetArg(args[n] , XmNmarginHeight, 300); n++; 

drawArea = XtCreateManagedWidget ("drawArea", xmDrawingAreaWidgetClass, 
rowColumn, args, n) ; 

/* add an expose callback */ 
XtAddCallback (drawArea, XmNexposeCallback, drawArea_CB,, NULL) ; 
n = 0; /* create a quit button */ 
XtSetArg(args[n], XmNlabelString, ^ 
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XmStringCreate ("Click here to quit the program.", 
XmSTRING_DEFAULT_CHARSET) ) ; n++; 
buttonFont = /* look for Helvetica Bold font */ 

XLoadQueryFont (XtDisplay (topLevel) , "-*-Helvetica-Bold-R-Normal — 
14*") ; 
if (buttonFont) /* if we found it, set fontList */ 
{ /* resource on the button */ 

XtSetArg(args [n] , XmNfontList, 
XmFontListCreate (buttonFont , XmSTRING_DEFAULT_CHARSET) ) ; 
n++; 
} 
quitButton = 

XtCreateManagedWidget ("quit", xmPushButtonGadgetClass, rowColumn, 
args, n) ; 

/* add an activation callback */ 
XtAddCallback (quitButton, XmNactivateCallback, quit_CB„ NULL); 

XtRealizeWidget (topLevel) ; /* realize widget hierarchy */ 

/* Begin PHIGS calls */ 
StartPhigs (XtDisplay (drawArea) , Xt Window (drawArea) ) ; 



/* 

Get_e vents 

This routine handles event processing. It simply obtains events from the 
toolkit via XtNextEvent and dispatches them to the widgets via 
XtDispatchEvent . This continues until the boolean done becomes True. This 
happens when the quit button's activation callback is invoked. 
*/ 

Get_e vents (dpy) 
Display *dpy; 
{ 

XEvent event ; 

done = False; 

do { 

XtNextEvent (Sevent) ; 
XtDispatchEvent (&event) ; 
} while ( !done) ; 
} 
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phigs2.c 

/* 

phigs2 .c 

This file contains the PHIGS specific calls for example program 2. 

Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990 f Evans & Sutherland 

*/ 

#include <X11/Xlib.h> 
#include <Xll/phigs/phigs .h> 

tinclude "header2.h" /* Local includes */ 

/* 

Error_Check 

This routine checks the global variable used to store error codes returned 
from PEX. If the error code is non-zero, it prints out a diagnostic message 
and dies . 

*/ 

void Error_Check (File, Line, Routine) 
char *File, *Routine; 
int Line; 
{ 

if (PEX_error) 
{ 

fprintf (stderr, "(file %s; line %d):\n", File, Line) ■; 
fprintf (stderr, "\t?unexpected PEX error %d in routine %s\n", 

PEX_error, Routine) ; 
exit ( 1 ) ; 
} 
} 

/* 
StartPhigs 

This routine is the top level routine that calls all supporting routines 
in the logical order of a usual phigs routine i.e., open PEX, setup the 
workstation parameters, define the phigs structure and then go into the 
event loop. 

*/ 
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StartPhigs (dpy, win) 
Display *dpy; 
Window win; 



/* Routine to start phigs calls */ 



} 



OpenPex(dpy) ; /* Open PEX 

SetupWorkstation(dpy, win); /* Setup PHIGS workstation parameters 



Make_boxes () ; 
Get_e vents (dpy) ; 
Cleanup ( ) ; 



/* Create Phigs structures 
/* Event loop 



*/ 
*/ 
*/ 
*/ 



/* Cleanup phigs structures close workstation */ 



/* 

OpenPex 



This routine Opens PEX on the display that was passed as an argument. 



*/ 



OpenPex (dpy) 
Display *dpy; 



Pxphigs_info xinfo; 
unsigned long infomask; 

xinfo. display = dpy; 
xinfo . rmdb = NULL; 
xinfo.appl_id.name = NULL; 
xinfo. appl_id. class = NULL; 
xinfo. args .argc_p = NULL; 
xinfo. args .argv = NULL; 
xinfo. flags .no_monitor = 1; 
xinfo.flags.force_client_SS = 0; 

infomask = PXPHIGS_INFO_DISPLAY | PXPHIGS_INFO_FLAGS_NO_MON; 

/* Open Pex */ 
popen_xphigs( (char*) NULL, PDEF_MEM_SIZE, infomask, &xinfo) ; 



/* 

SetupWorkstation 

This routine opens a PHIGS workstation and sets up a PHIGS Viewport. The 
structure edit mode is set to insert elements and the display update state 
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is set to PWAIT. The event mask for X input is set to select KeyPress and 

Expose events . 

*/ 



SetupWorkstation (dpy, win) 
Display *dpy; 
Window win; 

{ 

Pconnid__x_drawable conn; 

Pview__rep3 vrep; 

Pview__map3 map; 

PpointS vrp r cntr; 

Pvec3 vup; 

Pvec3 vpn; 



/* Open an Xwindow workstation */ 



/* Declare viewporting variables */ 



C 



conn. display = dpy; 
conn.drawable id = win; 



/* Open WS */ 
popen_ws(WS, (Pconnid *) (&conn) f phigs_ws_type_x_drawable) ; 

/* Setup viewport parameters */ 



map.proj_type = PTYPEJPARAL; 
map . vp . x_min = 0.0; map . vp . x_max = 1.0; 
map . vp . y_min = 0.0; map . vp . y__max = 1.0; 
map . vp . z_min = 0.0; map . vp . z_max = 1.0; 

map . win . x_min= -1.5; map . win . x_max= 1.5; 
map . win . y_min= -1.5; map . win . y_max= 1.5; 



/* Set projection type */ 
/* Set viewport limits */ 



/* Set window limits 



"/ 



map.back_plane = -2.0 
map . f ront jplane = 1.0 
map . view_plane = 0.0 



/* Set the front and back clipping planes */ 
/* Set the location of the view plane */ 



C 



map.proj_ref_j?oint .x = 1.0; 

/* Set projection Reference point to be offset */ 

map.proj_ref_point .y = -1.5; 

/* from the VRP (eye) in VRC space to give an */ 

map.proj_ref_point .z = 3.0;/* angle view of the objects.*/ 

vrep.xy_clip = PIND_NO_CLIP; /* Turn Viewport clipping off */ 
vrep. back_c lip = PIND_NO_CLIP; /* not to be confused with the */ 
vrep.front_clip = PIND_NO_CLIP; /* clipping at the viewplanes ! */ 



C 
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vrep.clip_limit = map.vp; /* Set Viewport clipping volume = viewport */ 

/* Setup View Reference Coordinates */ 

vrp.x = 0.0; vrp.y = 0.0; vrp.z = 1.0; /* Set View ref point */ 

/* Set view up vector */ 

vup.delta_x = 0.0; vup.delta_y = 1.0; vup.delta_z = 0.0; 

/* Set view plane normal*/ 

vpn.delta_x = 0.0; vpn.delta_y = 0.0; vpn.delta_z = 1.0; 

peval_view_ori_matrix3 (&vrp, &vpn, &vup, /* Evaluate orient matrix */ 
&PEX_error, vrep.ori_matrix) ; 

SAFE_PEX("peval_view_ori_matrix3") ; /* Check for error status */ 

peval_view_map_matrix3 ( &map, &PEX_error, /* Evaluate map matrix */ 

vrep .map_matrix) ; 

SAFE_PEX("peval_view_map_matrix3") ; /* Check for error status */ 

pset_view_rep3 ( WS, VIEW, &vrep ); /* Set the view representation */ 



pset_edit_mode (PEDIT_INSERT) ; /* Set edit mode to insert elements */ 
pset_disp_upd_st (WS, PDEFER_WAIT, PMODE_NIVE) ; 

/* Set update state to WAIT */ 
pset_hlhsr_mode(l, PHIGS_HLHSR_MODE_ZBUFF) ; /* Enable WS Z buffering */ 



/* 

Make_boxes 

Make_boxes defines a polyline cube and a fillarea cube in 3 
dimensions. Structures POLYBOX and FILLBOX are defined to contain 
these data elements along with color and style attributes to be applied 
to the data elements. A higher level structure DISPLAY_STRUCT is defined 
to include both the POLYBOX and FILLBOX structures and is then 
posted to the open workstation to be displayed. The workstation is then 
updated, causing the objects to be displayed. 
*/ 

Make_boxes () 
{ 
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/* Define polyline cube vectors */ 

static Ppoint3 line_pointsl []= /* Define points for front face */ 
{{ 0.5, 0.5, 0.5} , { 1.0, 0.5, 0.5} , 

{ 1.0, 1.0, 0.5} , { 0.5, 1.0, 0.5} , 

{ 0.5, 0.5, 0.5}}; 

static Ppoint3 line_points2 []= /■* Define points for back face */ 
{{ 0.5, 0.5, 0.0} , { 1.0, 0.5, 0.0} , 

{ 1.0, 1.0, 0.0} , { 0.5, 1.0, 0.0} , 

{ 0.5, 0.5, 0.0}}; 

static Ppoint3 line_points3 []= /* Define connecting line */ 
{{ 0.5, 0.5, 0.5} , { 0.5, 0.5, 0.0}}; 

static Ppoint3 line_j>oints4 []= /* Define connecting line */ 
{{ 1.0, 0.5, 0.5} , { 1.0, 0.5, 0.0}}; 

static Ppoint3 line_points5 []= /* Define connecting line */ 
{{ 1.0, 1.0, 0.5} , { 1.0, 1.0, 0.0}}; 

static Ppoint3 line_points6 [] = /* Define connecting line */ 
{{ 0.5, 1.0, 0.5} , { 0.5, 1.0, 0.0}}; 



/■* Define solid cube faces */ 

static Ppoint3 f ill_pointsl []= /* Define points for front face */ 
{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5} , 
{ 0.0, 0.0, 0.5} , { -0.5, 0.0, 0.5}}; 

static Ppoint3 f ill_j?oints2 []= /* Define points for back face */ 
{{ -0.5, -0.5, 0.0} , { 0.0,-0.5, 0.0} , 
{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 

static Ppoint3 f ill_points3 []= /* Define points for right face */ 
{{ 0.0, -0.5, 0.5} , { 0.0, -0.5, 0.0} , 
{ 0.0, 0.0, 0.0} , { 0.0, 0.0, 0.5}}; 

static Ppoint3 f ill_points4 []- /* Define points for left face */ 
{{ -0.5, -0.5, 0.5} , { -0.5, -0.5, 0.0} , 
{ -0.5, 0.0, 0.0} , { -0.5, 0.0, 0.5}}; 

static Ppoint3 f ill_points5 []= /* Define points for bottom face */ 
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{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5} , 
{ 0.0, -0.5, 0.0} , { -0.5, -0.5, 0.0}}; 

static Ppoint3 f ill_points6 []= /* Define points for top face */ 
{{ -0.5, 0.0, 0.5} , { 0.0, 0.0, 0.5} , 
{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 

Ppoint_list3 Line_list [5] , Fill list [5] ; 



popen_struct (POLYBOX) ; /* Open line drawing structure */ 
pset_line_colr_ind(2) ; /* Assign default index color 2 to lines*/ 

Line_list[0] .num_points = 5; /* Fill in number of points in list */ 
Line_list [0] .points = line_j?ointsl; /* Pointer to point array */ 
ppolyline3 (&Line_list [0] ) ; /* Create a polyline element */ 

pset_line_colr_ind(3) ; /* Assign default index color 3 to lines*/ 

Line__list [1] .num_points = 5; 
Line_list [1] .points = line_points2; 
ppolyline3 (&Line_list [1] ) ; 

pset_line_colr_ind(4) ; /* Assign default index color 4 to lines*/ 
Line_list [2] .num_points = 2; 
Line_list [2] .points = line_points3; 
ppolyline3 (&Line_list [2] ) ; 

pset_line_colr_ind(5) ; /* Assign default index color 5 to lines*/ 
Line_list [3] .nurnjpoints = 2; 
Line_list [3] .points = line_jpoints4; 
ppolyline3 (&Line_list [3] ) ; 

pset_line_colr_ind(6) ; /* Assign default index color 6 to lines*/ 
Line_list [4] .nurnjpoints = 2; 
Line_list [4] .points = line_points5; 
ppolyline3 (&Line_list [4] ) ; 

pset_line_colr_ind(7) ; /* Assign default index color 7 to lines*/ 
Line_list [5] .num_points = 2; 
Line_list [5] .points = line_jpoints6; 
ppolyline3 (&Line_list [5] ) ; 

pclose_struct () ; /* Close line drawing structure */ 
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popen_struct (FILLBOX) ; /* Open filled drawing structure */ 
pset_int_style(PSTYLE_SOLID) ; /* Set interior style to be solid */ 
pset_int_colr_ind(7) ; /* Assign default index color 7 to face */ 

Fill_list [0] .num_j>oints = 4; /* Fill in number of points in list */ 
Fill_list [0] .points = f ill_j?ointsl; /* Pointer to point array */ 
pfill_area3 (&Fill_list [0] ) ; /* Create a fill area element */ 

pset_int_colr_ind(3) ; /* Assign default index color 3 to face */ 
Fill_list [1] .numjpoints = 4; 
Fill_list [1] .points = f ill_points2; 
pf ill_area3 (&Fill_list [1] ) ; 

pset_int_colr_ind(2) ; /* Assign default index color 2 to face */ 
Fill_list [2] .num_points = 4; 
Fill_list [2] .points = f ill_points3; 
pf ill_area3 (&Fill_list [2] ) ; 

pset_int_colr_ind(4) ; /* Assign default index color 4 to face */ 
Fill_list [3] .num_j>oints = 4; 
Fill_list [3] .points = f ill_points4; 
pf ill_area3 (&Fill_list [3] ) ; 

pset_int_colr_ind(5) ; /* Assign default index color 5 to face */ 
Fill_list [4] .num_points = 4; 
Fill_list [4] .points = f ill_points5; 
pfill_area3(&Fill_list[4]) ; 

pset_int_colr_ind(6) ; /* Assign default index color 6 to face */ 

Fill_list [5] .num_points = 4; 

Fill_list [5] .points = f ill_points6; 
pf ill_area3 (&Fill_list [5] ) ; 

pclose_struct () ; /* Close filled drawing structure */ 

popen_struct (DISPLAY_STRUCT) ; /* Open the top level display structure */ 

pset_view_ind(VIEW) ; /* Set the view index to be used */ 

pset_hlhsr_id(PHIGS_HLHSR_ID_ON) ; /* Turn on Z buffering */ 

pexec_struct (FILLBOX) ; /* Include the filled square */ 

pexec_struct (POLYBOX) ; /* Include the line drawn square */ 

pset_hlhsr_id(PHIGS_HLHSR_ID_OFF) ; /* Turn off Z buffering */ 

pclose_struct () ; /* Close the structure */ 

ppost_struct (WS, DISPLAY_STRUCT f 1.0); /* Post DISPLAY_STRUCT, prio 1 */ 
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pupd_ws(WS, PUPD_PERFORM) ; /* Update the workstation */ 

} 



Cleanup () /* cleanup routine when done */ 

{ 

punpost_all_structs (WS) ; /* Unpost all structures on ws */ 

pdel_all_structs() ; /* Delete all structures */ 

pclose_ws(WS) ; /* Close workstation */ 

pclose_phigs() ; /* Close PHIGS */ 

} 
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header2.h 

/* 

header2 .h 
This file contains header information for the example 2 programs . 

Author: James Buckmiller May 1990. 

Copyright (C) 1990, Evans & Sutherland 
*/ 

#define WS 1 

#define POLYBOX 1 /* define some constants to be used later */ 

#define FILLBOX 2 

#define DISPLAY_STRUCT 3 

#define VIEW 4 

#define SAFE_PEX (routine) Error_Check( FILE , LINE , routine) 

extern Window myWin; 
extern Display *dpy; 
extern char *ProgramName; 

extern Pint PEX error;/* for PEX error number handling */ 



C 



c 
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examples. c 



/* 



example3 .c 



This program defines and displays two boxes on the open PEX workstation. 
One box is a 3d polyline object and the other is a 3d fillarea object. This 
program incorperates a PHIGS view representation. The view is set to 
encompass -1.5 to 1.5 in model space coordinates with a parallel projection 
matrix. This program incorporates dials input to update the transformation 
matrices that are in the display structure. This program shows command line 
arguments to handle Xlib environment calls as well as an event loop. To 
reset the picture press the r key on the keyboard. To exit the client press 
the e key on the keyboard. 



Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 



Copyright (C) 1990, Evans & Sutherland 

*/ 

#include <X11/Xlib.h> 

#include <Xll/Xproto .h> 

#include <Xll/Xatom.h> 

#include <Xll/extensions/XInput .h> 

#include <Xll/phigs/phigs .h> 

tinclude <Xll/keysymdef .h> 



#include "header3 . h" 



/* local includes */ 



Window my Win ; 
Display *dpy; 
char *ProgramName; 
Pint PEX error; 



/* drawing window */ 

/* Xll display connection */ 

/* For PEX error numbers */ 



main(argc, argv) 
int argc; 
char *argv[] ; 
{ 

int i ; 

char *geom = NULL; 

char ^display = NULL; 
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int winposx, winposy, winwidth, winheight; 

ProgramName = argv[0]; 

winposx = 100; 
winposy = 100; 
winwidth = 600; 
winheight = 600; 



/* default window geometry */ 



for (i=l; i < argc; i++) 
{ 

char *arg = argv[i], 

if (arg[0] == '-') 
{ 

switch (arg[l]) 



/* Parse the command line .■'*/ 



case ' d f : 

if (++i >= argc) usage () ; 
display = argv[i]; 

continue; 
case ' g' : 

if (++i >= argc) usage () ; 
geom = argv[i] ; 

continue; 
default : 

usage () ; 



/* -display host:dpy */ 



/* -geometry host:dpy */ 



( 



} 



if ( ! (dpy = XOpenDisplay (display) ) ) /* Attempt to open the display */ 
{ 

perror ("Cannot open display\n") ; 

exit (-1) ; 
} 



if (geom) 

{ /* Generate position and size from the geometry string */ 
(void) XParseGeometry (geom, fiwinposx, &winposy f & winwidth, & winheight) ; 
} 

/* Create a simple, unmapped input/output window */ 
myWin = XCreateSimpleWindow (dpy, RootWindow(dpy, Def aultScreen (dpy) ) , 
winposx, winposy, winwidth, winheight, 0, NULL, NULL) ; 



C 
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/* Change the window name property */ 
XChangeProperty(dpy, myWin, XA_WM_NAME, XA_STRING, 8, 

PropModeReplace, "Example 3: r Key = Reset e Key = Exit", 40) 

/* Map the window for display */ 
XMapWindow(dpy, myWin) ; 



/* Begin PHIGS calls 
StartPhigs (dpy, myWin) ; 



V 



} 

/* 

usage 



This routine prints out command line argument information if the user 
supplied arguments are incorrect. 



usage () 



fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
exit (1); 



usage: %s [-options ...]\n\n", ProgramName) ; 
where options include : \n") ; 

-display host: dpy X server to use\n") ; 

-geometry geom geometry of window\n") , 

\n"); 



/* 

Get_e vents 

This routine is the event handling routine. First the usual X 
events are trapped. If an expose event occurs then a PHIGS 
redrawallstructures is called. If a Keyboard event occurs 
the keysym is reviewed to see if it is an "e" for exit or an 
"r" for a reset of the display. If the event that is generated 
is not a usual X event then it is check to be an extension 
event for dials events. If dials event then the object is 
transformed by rotates and translates in X,Y, Z and scale. 
*/ 



Get_e vents (dpy) 
Display *dpy; 
{ 
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XDevicelnfo * devices = NULL; 
XDevice *dials = NULL; 
XEventClass DeviceMotionClass [100] ; 
XID dials_id; 
XEvent report; 



C 



XKeyPressedEvent *pev; 
KeySyra key; 
char buf [20] ; 

unsigned long event_mask; 

XButtonPressedEvent *bdown; 

XButtonReleasedEvent *bup; 

Atom dials_atom = 0; 

int knob_totals [MAXDIALS] ; 

XStringFeedbackControl strfc; 

int done=0; 

KeySym ledst ring [MAXDIALS] [CHARS_PER_DIAL] , blankled[CHARS_PER_DIAL] ; 



Pmatrix3 composite; 

static Pmatrix3 currmatrix[] = 

{{1,0,0,0}, {0,1,0,0}, {0,0,1,0}, {0,0, 0,1}}; 

Pvec3 scale, trans; 

int ndevices = 0, i, j, EventCount = 0, DeviceMotion = -1; 

int rotx=0, roty=0, rotz=0; 

Ppoint3 cntr; 



( 



/* Dial Labels */ 
static char text string [MAXDIALS] [CHARS_PER_DIAL] = 

{ " X ROT ", " Y ROT ", " Z ROT " , 
" SCALE ", "X TRAN ", " Y TRAN ", 
■ " Z " TRAN " , " »j . 



cntr .x = 0.0; 
cntr.y =0.0; 
cntr.z = 0.0; 
scale. delta_x = 1.0, 
scale. delta_y = 1.0 
scale. delta_z = 1.0 
trans .delta_x =0.0, 
trans .delta_y = 0.0 
trans. delta z = 0.0 



/* Define center point of transformations */ 



/* Define initial scale to be 1 



/* Define initial translation to be 



C 
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/* Get the atom ID for the Knob box */ 
dia!s_atom = XInternAtom(dpy f "KNOB_BOX", True) ; 

/* Get list of Input devices */ 
devices = XListlnputDevices (dpy, &ndevices) ; 

/* Find the dials device in the list and open the device */ 

for (i = 0; i < ndevices; i++, devices++) 
if ( (devices->type == dials_atom) && 

(devices->use == IsXExtensionDevice) ) 
{ 

dials_id = devices->id; 

dials = XOpenDe vice (dpy, dials_id) ; /* Get Xdevice structure */ 
break; /* for the dials */ 

} 

if (Idials) 
{ 

fprintf (stderr, "?dials box not found in X extension device list.\n"); 
exit(l); 
} 

/* Get event class values for dials */ 
DeviceMotionNotify (dials, DeviceMotion, DeviceMotionClass [EventCount] ) ; 
EventCount ++; 

/* Tell server to pass on Extension events */ 
XSelectExtensionEvent (dpy, myWin, DeviceMotionClass, EventCount); 

/* Set the event mask for the window */ 
XSelectlnput (dpy, myWin, EnterWindowMask | LeaveWindowMask 
I KeyPressMask | ExposureMask) ; 



for (i =0; i < MAXDIALS; i++) /* Load the keysym arrays */ 

for (j = 0; j < CHARS_PER_DIAL; j++) 
{ 

ledstring[i] [j] = (KeySym) textstring[i] [ j] ; /* Dial labels */ 
blankled[j] = SPACEKEYSYM; ./* Blank labels */ 

} 

strfc. class = StringFeedbackClass; 

strfc. length = sizeof (XStringFeedbackControl) ; 

strfc.num_keysyms = CHARS_PER_DIAL; 

for (i=0; KMAXDIALS; i++) /* Set the dial labels */ 
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{ 

strfc.id = i; 

strfc.syms_to_display = ledstring[i] ; 

XChangeFeedbackControl (dpy, dials, DvString, &strfc) ; 

} 

while ( Sdone) 
{ 

XNextEvent (dpy, Sreport) ; /* Get next event from event queue */ 
if (report. type < LASTEvent) /* Check if extension event or not */ 
{ 

switch (report .type) 
I 

case EnterNotify: /* Turn on the dial labels */ 

for (i=0; KMAXDIALS; i++) /* when the cursor enters */ 
{ /* the window. */ 

strfc.id = ij- 
strfc .syms_to_display = ledstring[i] ; 
XChangeFeedbackControl (dpy, dials, DvString, Sstrfc) ; 
} 
break; 

case KeyPress: /* Trap keyboard events */ 

/* and perform function. */ 
pev = (XKeyPressedEvent *) & report ; 
XLookupString(pev, buf, sizeof(buf), &key, NULL) ; 
if(buf[0] == f r f ) /* reset picture */ 

{ 

make_identity (currmatrix) ; /* Currmatrix = identity matrix */ 

Make_boxes ( ) ; /* Rebuild the structures*/ 

/* Reset xformation parameters */ 

scale. delta_x = scale. delta_y = scale. delta_z = 1.0; 

trans. delta_x = trans .delta_y = trans .delta_z = 0.0; 

rotx = roty = rotz =0; 

}. 
if(buf[0] == f e') /* Exit application */ 

done = 1; 
break; 

case Expose: /* expose events = redraw */ 

predraw_all_structs(WS, PFLAG_ALWAYS) ; 
break; 

case LeaveNotify: /* Blank LEDs when cursor leaves window */ 
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for (i=0; KMAXDIALS; i++) 
{ 

strfc.id = i; 

strfc.syms_to_display = blankled; 

XChangeFeedbackControl (dpy, dials, DvString, &strfc) ; 
} 
break; 



} 

/* else it's an extension event */ 
else if (report. type == DeviceMotion) /* Dials input */ 

{ 

XDeviceMotionEvent *dm = (XDeviceMotionEvent *) & report; 
for (i=0; KMAXDIALS; i++) /* Initialize knob values array */ 
knob_totals [i] = 0; 

/* _ _ 

The following piece of code goes out to the event queue and scoops 

off all dial motion events that are found on the queue with the 

XCheckTypedEvent call. These events are then accumulated for each 

axis and then processed with the accumulated values. 

The reason for doing this is to increase the performance of the 

system. If an update of the workstation display is performed 

for every dial event that occurs the display will get behind thus 

causing a lag time between when the dials stop sending events and 

the system finishes unpiling the event queue. 

For this application grabbing all dial events off the queue works 

well however, one must beware that if an application allows the 

dials to be redefined with some other event (function key or pick 

menu) this method may not be the way to get the dial events since 

there may be keypress or pick events intermixed with the dials 

events. To get around this problem one may wish to use the 

XPeekEvent routine to look ahead one event to be sure that it is 

the same event class as the ones being accumulated. 

v 

do /* Collapse the events before processing */ 

for (i=0; i < dm->axes_count ; i++) 

knob_totals [dm->f irst_axis+i] += dm->axis_data [i] ; 

/* Gather all dial events from the event queue */ 
while (XCheckTypedEvent (dpy, DeviceMotion, dm) ) ; 

/* Process DeviceMotion events */ 
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if (knob_totals [0] ) /* dial 1 input check rot x */ 

rotx += knob_totals [0] ; 

if (knob_totals [1] ) /* Dial 2 input check rot y */ 

roty += knob_totals [1] ; 

if (knob_totals[2] ) /* Dial 3 input check rot z */ 

rotz += knob_totals [2] ; 

if (knob_totals [3] ) /* Dial 4 input check uniform scale */ 

{ 

scale. delta_x += knob_totals [3] * DIALSCALE; 

scale. delta_y += knob_totals [3] * DIALSCALE; 

scale. delta_z += knob_totals [3] * DIALSCALE; 
} 

if (knob_totals [4] ) /* Dial 5 input check trans x */ 

trans. delta_x += knob_totals [4] * DIALSCALE; 

if (knob_totals [5] ) /* Dial 6 input check trans y */ 

trans. delta_y += knob_totals [5] * DIALSCALE; 

if (knob_totals [6] ) /* Dial 7 input check trans z */ 

trans. delta_z += knob_totals [6] * DIALSCALE; 

/* Build the transformation matrix */ 
pbuild_tran_matrix3 (Scntr, fitrans, DEG_TO_RAD (rotx) , DEG_TO_RAD (roty) 
r DEG_TO_RAD(rotz) , fiscale, &PEX_error 
, currmatrix) ; 
SAFE_PEX("pbuild_tran_matrix3") ; /* Check for error status */ 

popen_struct (DISPLAY_STRUCT) ; /* Open structure for editing */ 

{ 

pset_elem_j?tr (0) ; /* Reset element pointer */ 

pset_elem_ptr_label (TRANS) ; /* Find transformation label */ 
poffset_elem_j)tr (1) ; /* Point at matrix */ 

/* replace matrix */ 
pset_local_tran3 (currmatrix, PTYPE_PRECONCAT) ; 
} 
pclose_struct () ; /* Close structure */ 

predraw_all_structs(WS, PFLAG_ALWAYS) ; /* Redraw the structure */ 

} 
} 
} 
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motifS.c 

/* 

m o t i f 3 . c 

This program expands on motif2 to display true 3D objects and handling of 
events from the dials box. The objects displayed are a 3D solid cube 
created using FILL AREA 3 structure elements and a 3D wire-frame cube 
created using POLYLINE 3 structure elements. This program incorporates a 
3D PHIGS view representation to view the objects. The view implements a 
parallel projection whose view volume extends from -1.0 to 1.5 on all 
three axes of model space. 

The dials box controls viewing of the objects via a transformation matrix 
in the structure, allowing an arbitrary translation, rotation and scale 
about the origin. Setting the labels on the dials box only when the 
core pointer is inside the drawing window aids in feedback to the user 
as to when dial events are processed. 

In addition to the widgets in motif 2, this program adds a reset button to 
reset the viewing transformation matrix to its original state (useful 
when you've lost the object due to translations and/or scaling) . 

Author: Rich Thomson 

Date: Thursday, June 12th, 1990 

Modified: J. Buckmiller Mar 1991. Approved C binding 



Copyright (C) 1990, Evans & Sutherland Computer Corporation 



"/ 



#include <X11/Xlib.h> 

#include <Xll/Xatom.h> 

#include <Xll/extensions/XInput ,h> 

#include <Xll/phigs/phigs .h> 

#include <X11/Intrinsic ,h>/* toolkit intrinsics */ 
#include <Xm/RowColumn.h>/* row column widget */ 
#include <Xm/DrawingA.h>/* drawing area widget */ 
#include <Xm/PushBG.h>/* push button gadget */ 

tinclude "header3.h" 

Display *dpy;/* Xll display connection */ 
char *ProgramName; 

int DeviceMotion; /* device motion event type */ 
Window drawWindow; /* drawing window */ 
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Pint PEX_error; /* For PEX error numbers */ 

static XDevice *dials = NULL; /* dials device */ 

static Pmatrix3 currmatrix = { {1, 0, 0, 0} , {0, 1, 0, } , {0, 0, 1, } , { 0, 0, 0, 1 } } ; 

static Boolean done = False; 

static Pvec3 scale ={1.0,1.0,1.0}; /* scale factors */ 

static Pvec3 trans ={0.0,0.0,0.0}; /* translation vector '*/ 

static Pint rotx = 0, roty = 0, rotz = 0; /* axis rotation amounts *■/' 

/* 

quit_CB 

The callback procedure for the quit pushbutton widget. It simply sets the 
event processing exit flag to True, which will cause Get_events to 
stop processing events. 

*/ 

void quit_CB( quit But ton, client_data, call_data) 
Widget quitButton; 
caddr__t client_data; 
XmAnyCallbackStruct *call_data; 
{ 

if (call_data->reason == XmCR_ACTIVATE) 
done = True; 
} 

/* 

reset__CB 

The callback procedure for the reset button. It re-initializes the 
parameters that define the transformation matrix corresponding to 
translate, rotate and scale operations and recreates the initially posted 
structures . 

*/ 

void reset_CB (resetButton, client_data, call_data) 
Widget resetButton; 
caddr_t client_data; 
XmAnyCallbackStruct *call_data; 
{ 

if (call_data->reason == XmCR_ACTIVATE) 
{ 

Make_boxes () ; /* recreate initial structures */ 



C 



C 



c 
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/* reset xformation parameters */ 
scale. delta_x = scale .delta_y = scale. delta_z - 1.0; 
trans. delta_x = trans .delta_y = trans .delta_z = 0.0; 
rotx = roty = rotz =0; 



/* 

drawArea_CB 

The callback procedure for the drawing area widget . It redraws all 

the structures on the workstation. 

*/ 

void drawArea_CB (drawArea, client_data, call_data) 

Widget drawArea; 

caddr_t client_data; 

XmDrawingAreaCallbackStruct *call_data ; 



{ 



if (call_data->reason == XmCR_EXPOSE) 
predraw_all_structs(WS, PFLAG_ALWAYS) , 



/* 

knob_labels 

This array holds the KeySym' s that contain the knob labels. It is used by 
the enter and leave window handlers to blank out the labels when the 
pointer is not in the drawing area window. 

Dial labels are CHARS_PER_DIAL KeySyms per dial. Ascii characters can be 
converted to KeySyms by C type casting. 

*/ 

static KeySym knob_labels [MAXDIALS] [CHARS_PER_DIAL] ; 

/* 

enter_handler 

This event handler restores the knob labels to our labels when the 
pointer moves into the drawing window. Conditionally labelling the dials 
in this way gives extra feedback to the user that the dials are active 
only when the mouse is inside the appropriate window. 

*/ 
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void enter_handler (widget, client_data, event, continue_to_dis patch) 
Widget widget; 
caddr__t client_data; 
XEvent *event; 

Boolean *continue_to_dispatch; 
{ 

register int i; 
XStringFeedbackControl strfc; 

strfc. class = StringFeedbackClass;/* initialize the feedback struct */ 
strfc. length = sizeof (XStringFeedbackControl) ; 
strfc.num_keysyms = CHARS_PER_DIAL; 

for (i = 0; i < MAXDIALS; i++) /* for each dial */ 
{ 

strfc. id = i;/* number of dial to set feedback on */ 
strfc. syms_to_di splay = knob_labels [i] ; 
/* keysyms containing feedback */ 
XChangeFeedbackControl (dpy, dials, DvString, Sstrfc) ; 
} 
} 

/* 
leave_handler 

This event handler blanks the knob labels when the pointer leaves the 
drawing window. 

*/ 

void leave_handler (widget, client_data, event, continue_to_dispatch) 

Widget widget ; 

caddr_t client_data; 

XEvent *event ; 

Boolean *continue_to_dispatch; 
{ 

static XStringFeedbackControl strfc; 
static KeySym blanks [CHARS_PER_DIAL] ; 
static Boolean initialized = False; 
register int i; 

if (Unitialized)/* initialize variables the first */ 
/* time we're called */ 
{ 

for (i = 0; i < CHARS_PER_DIAL; i++) 
blanks [i] = (KeySym) r ' ; /* prepare a blank keysym array */ 
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strfc. class = StringFeedbackClass; 

/* initialize the feedback struct */ 
strfc. length = sizeof (XStringFeedbackControl) ; 
strfc.num_keysyms = CHARS_PER_DIAL; 
strfc.syms_to_display = blanks; 

initialized = True; /* remember we've been initialized */ 

} 

for (i = 0; i < MAXDIALS; i++) /* for each dial */ 
{ 

strfc. id = i; /* indicate which dial to change */ 

/* change it */ 
XChangeFeedbackControl(dpy, dials, DvString, fistrfc) ; 
} 
} 

/* 

open_knob 

This routine opens the knob box on the given display and selects device 
motion extension events on the given window. Extension events are 
selected by first invoking the appropriate macro on an XEventClass 
structure (in this case DeviceMotionNotify) and then calling 
XSelectExtensionEvent . 
*/ 

void open_knob() 
{ 

/* dial labels as ascii strings */ 
static char text string [MAXDIALS] [CHARS_PER_DIAL] = { 
" X ROT ", " Y ROT ", " Z ROT "," SCALE ", 

" X TRAN ", " Y TRAN ", " z TRAN ", " " /* eighth label is blank */ 
}; 
register int knob, i; 

int ndevices;/* number of extension devices */ 
XDevicelnfo *devices = NULL;/* extension device info list */ 
Atom dials_atom = XInternAtom(dpy, "KNOB_BOX", True) ; 
/* intern device name into an atom */ 
XID dials_id; /* device ID for dials box */ 
XEventClass eventClass [1] ; 

devices = XListlnputDevices (dpy, &ndevices) ; /* get list of devices */ 
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for (i = 0; i < ndevices; i++, devices++) 

if ( (devices->type == dials_atom) && (devices->use == 
IsXExtensionDevice) ) 
{ /* did we find the dial box? */ 

dials_id = devices->id; /* yes, remember its device ID */ 
dials - XOpenDevice (dpy, dials_id) ; /* and open it */ 
break; /* we only want the first one. 

} 

if (Sdials)/* couldn't open or find dials */ 

{ 

fprintf (stderr, "?couldn f t open dials box.\n"); 
exit ( 1 ) ; 

} 

/* select device motion events */ 
DeviceMot ionNot if y (dials, DeviceMotion, eventClass [0] ) ; 
XSelectExtensionEvent (dpy, drawWindow, eventClass, 1) ; 

for (knob = 0; knob < MAXDIALS; knob++) 

/* convert ascii labels to KeySyms */ 
for (i = 0; i < CHARS_PER_DIAL; i++) 

knob__labels[knob] [i] = (KeySym) textstring [knob] [i] ; 
} 

/* 

main 



C 



( 



The main routine creates the widget hierarchy for the program, opens the 
knob box and then calls StartPhigs . StartPhigs will then call Get_events 
to initiate event processing. 
The widget hierarchy used here is : 

motif3 (class topLevelShell) 
I 
+ — rowcol (class RowColumn) 

I 

+ drawArea (class DrawingArea) 

I 

+ reset (class PushButtonGadget) 

I 

+— quit (class PushButtonGadget) 
The row column widget is used for organizing its child widgets into a 
columnar layout. The drawing area widget is used for PEX operations and 
the PEX workstation is opened on its window. The two push buttons are 

--"— c 
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Any necessary resources for the widgets are specified here in the 
program, which override any user defaults or command-line options. Note 
that this is not very friendly to the user who may want to change the 
font of the push buttons. A friendlier way is to provide an application 
defaults file which the user may override with user defaults or 
command-line arguments. For simplicity, I have set the arguments here 
directly. 

The display connection (dpy) and window ID (drawWindow) of the drawing 
area widget are available after the widget hierarchy has been realized. 

BEWARE ! ! BEWARE ! ! 

The drawing area widget in Motif 1.0 has a bug in that it ignores 
height and width resources supplied at creation time. A workaround 
I've found is to set the margins of the drawing area to be half the 
desired height and width. Since the margins specify the boundary 
between the drawing area widget's border and any children of the 
drawing area widget (we have none here) , the drawing area widget will 
be sized to contain its children plus twice the margins in each 
direction. Hence to get a 600x600 drawing area widget, you can set the 
margins to 300. Other workarounds suggested involve creating the 
drawing area widget as a child of other widgets, but where there are no 
children of the drawing area, I prefer setting the margins. 

*/ 

main(argc, argv) 
int argc; 
char *argv[] ; 
{ 

Arg args[10];/* arg. array for widget resources */ 

register int n;/* resource count */ 

Widget topLevel, rowColumn, quitButton, resetButton, drawArea; 

XFontStruct *buttonFont ; /* font obtained from XLoadQueryFont */ 

XmFontList fontList;/* for setting widget's fontList */ 

ProgramName = argv[0]; 

/* create topLevelShell */ 
topLevel = Xt Initialize (ProgramName, "Example", NULL, 0, &argc, argv) ; 

n = 0; 

XtSetArg(args[n], XmNtitle, "Example 3"); n++; 

XtSetValues (topLevel, args, n) ; 

buttonFont =/* find the font we want for buttons */ 

XLoadQueryFont (XtDisplay (topLevel) , "-*-Helvetica-Bold-R-Normal — 
14*") ; 
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if (buttonFont) 

fontList = XmFontListCreate (buttonFont, XmSTRING_DEFAULT_CHARSET) ; 

rowColumn =/* create the row column for layout */ 

XtCreateManagedWidget ("rowcol", xmRowColumnWidgetClass, topLevel, 
NULL, 0); 

n = 0; /* create the drawing area for PEX */ 

XtSetArg(args[n] , XmNmarginWidth, 300); n++; /* size appropriately */ 
XtSetArg (args [n] , XmNmarginHeight, 300); n++; 

drawArea = XtCreateManagedWidget ("drawArea", xmDrawingAreaWidgetClass, 
rowColumn, args, n) ; 

/* add an expose callback */ 
XtAddCallback (drawArea, XmNexposeCallback, drawArea_CB, NULL); 

/* add event handlers to handle */ 
/* blanking of knob labels */ 
XtAddE vent Handler (drawArea, EnterWindowMask, False, enter_handler, 

NULL) ; 
XtAddEventHandler (drawArea, LeaveWindowMask, False, leave_handler, 
NULL) ; 

n = 0; /* create the reset button */ 

XtSetArg(args [n] , XmNlabelString, 

XmStringCreate ("Click here to reset the picture.", 
XmSTRING_DEFAULT_CHARSET) ) ; n++; 
if (buttonFont) 

{ 

XtSetArg(args [n] , XmNfontList, fontList); n++; 

} 
resetButton = XtCreateManagedWidget ("reset", xmPushButtonGadgetClass, 
rowColumn, args, n) ; 

/* add it's activation callback */ 
XtAddCallback (resetButton, XmNactivateCallback, reset_CB, NULL); 

n = 0; /* create the quit button */ 
XtSetArg(args [n] , XmNalignment, XmALIGNMENT_CENTER) ; 
XtSetArg (args [n] , XmNlabelString, 

XmStringCreate ("Click here to quit the program.", 
XmSTRING_DEFAULT_CHARSET) ) ; n++; 
if (buttonFont) 
{ 

XtSetArg (args [n] , XmNfontList, fontList); n++; 

} 
quitButton = 
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XtCreateManagedWidget ("quit", xmPushButtonGadgetClass, rowColumn, 
args, n) ; 

/* add it's activation callback */ 
XtAddCallback(quitButton, XmNactivateCallback, quit_CB, NULL); 

XtRealizeWidget (topLevel) ; /* realize widget hierarchy */ 

dpy = XtDisplay (drawArea) ;/* obtain the display connection */ 
drawWindow = Xt Window (drawArea) ; /* and the drawing area's window ID */ 

open_knob (dpy) ; /* open the knob box */ 

StartPhigs (dpy f drawWindow);/* Begin PHIGS calls */ 



/* Get_e vents 

This routine processes events requested by the program. XtNextEvent 
obtains the next event from the input queue and places it in report. The 
type of the event is then examined to determine if it is an extension 
event or a regular X event. The constant LASTEvent (defined in X.h) is 
bigger than the event type of any X event and can be used to 
differentiate extension events from normal X events. 

Regular events are handled by the toolkit dispatch mechanism via 
XtDispatchEvent . Extension events (DeviceMotion) are handled on a 
case-by-case basis. 

When a DeviceMotion event is encountered, all device motion events are 
removed from the event queue and accumulated into knob_totals, since the 
dials box reports relative changes. Event explosion is a very real 
possibility since every device motion event requires 2 XEvent structures 
(only 6 axes' worth of data fit in a single XEvent) and the sample rate 
of the dials box is high. Since this program is only concerned with 
cumulative changes in the dials values, it is safe to condense the device 
motion events via XCheckTypedEvent . Since XCheckTypedEvent can remove 
events that are not at the head of the event queue, it may not be 
appropriate for situations where the semantics of a device motion event 
can be changed by another event (for instance, a key or button press) . 

*/ 

Get_e vents (dpy) 

Display *dpy; 

{ 

XEvent report; 
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int i; 

static Ppoint3 cntr = { 0.0, 0.0, 0.0 }; /* center at origin */ 

pset_edit_mode (PEDIT_REPLACE) ; /* Set edit mode to replace elements */ 

while ( !done) 
{ 

XtNextEvent (& report ) ; 

if (report. type < LASTEvent) 
XtDispatchEvent (& report) ; 

else if (report. type == DeviceMotion) /* must be device motion event */ 
{ 

XDeviceMotionEvent *dm = (XDeviceMotionEvent *) &report; 

int knob_totals [8] ; 

for (i = 0; i < MAXDIALS; i++) 

/* Initialize knob values array */ 
knob_totals [i] = 0; 

do /* Compress motion events */ 

for (i = 0; i < dm->axes_count; i++) 

knob_totals [dm->f irst_axis+i] += dm->axis_data [i] ; 
while (XCheckTypedEvent (dpy, DeviceMotion, dm) ) ; 

/* Process device motion events */ 
if (knob_totals[0]) /* dial 1 input check rot x */ 

rotx += knob_totals [0] ; 

if (knob_totals[l] ) /* Dial 2 input check rot y */ 

roty += knob_totals [1] ; 

if (knob_totals[2] ) /* Dial 3 input check rot z */ 

rotz += knob_totals [2] ; 

if (knob_totals [3] ) /* Dial 4 input check uniform scale */ 
{ 

scale. delta_x += knob_totals [3] * DIALSCALE; 

scale. delta_y += knob_totals [3] * DIALSCALE; 

scale. delta_z += knob_totals [3] * DIALSCALE; 
} 

if (knob_totals [4] ) /* Dial 5 input check trans x */ 

trans. delta x += knob totals [4] * DIALSCALE; 



1-172 ESV Workstation Reference Manual [2.0] 



c 



( 



c 



} 



ES/PEX 



if (knob_totals [5] ) /* Dial 6 input check trans y */ 

trans. delta_y += knob_totals [5] * DIALSCALE; 

if (knob_totals [6] ) /* Dial 7 input check trans z */ 

trans. delta_z += knob_totals [6] * DIALSCALE; 

/* Build the transformation matrix */ 
pbuild_tran_matrix3 (ficntr, &trans, DEG_TO_RAD (rotx) , 
DEG_TO_RAD (roty) 

r DEG_TO_RAD (rotz) , Sscale, &PEX_error 
f currmatrix) ; 
SAFE_PEX("pbuild_tran_matrix3") ; /* Check for error status */ 

/* Combine old and new matrices */ 

popen_struct (DISPLAY_STRUCT) ; /* Open structure for editing */ 
{ 

pset_elem_jDtr (0) ; /* Reset element pointer */ 

pset_elem_j?tr_label (TRANS) ; /* Find transformation label */ 
pof f set_elem_ptr (1) ; /* Point at matrix */ 

/* replace matrix */ 
pset_local_tran3 (currmatrix, PTYPEJPRECONCAT) ; 
} 

pclose_struct () ; /* Close structure */ 

predraw_all_structs (WS, PFLAG_ALWAYS) ; /* Redraw the structure */ 



} 
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/* ^ 

phigs3.c 

This program contains the phigs specific setup for example program 3. 

Author: James Buckmiller May 1990 

Modified: J. Buckmiller Mar 1991 Approved C binding 

Copyright (C) 1990, Evans & Sutherland 

*/ 

#include <X11/Xlib.h> 
#include <X1 1 /phigs /phigs .h> 

#include "header3.h" /* local includes */ 



/* 

Error__Check 

This routine checks the global variable used to store error codes 
returned from PEX. If the error code is non-zero, it prints out a 
diagnostic message and dies. 

*/ 

void Error_Check (File, Line, Routine) 
char *File, ^Routine; 
int Line ; 
{ 

if (PEX_error) 

{ 

fprintf (stderr, "(file %s; line %d):\n", File, Line); 
fprintf (stderr, "\t?unexpected PEX error %d in routine %s\n", 

PEX_error, Routine) ; 
exit(l); 
} 
} 



C 



( 
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/* 

StartPhigs 

This routine is the top level routine that calls all supporting 
routines in the logical order of a usual phigs routine ie 
open PEX, setup the workstation parameters, define the phigs 
structure and then go into the event loop. 
*/ 

StartPhigs (dpy, win) /* Routine to start phigs calls */ 

Display *dpy; 

Window win; 

{ 

OpenPex(dpy) ; /* Open PEX */ 

SetupWorkstation (dpy, win);/* Setup PHIGS workstation parameters */ 
Make_boxes () ; /* Create Phigs structures */ 

Get_events (dpy) ; /* Event loop */ 

Cleanup () ; /* Cleanup phigs structures close workstation */ 

} 



/* 

OpenPex 

This routine Opens PEX on the display that was passed as an argument. 
*/ 

OpenPex (dpy) 
Display *dpy; 
{ 

Pxphigs_info xinfo; 

unsigned long infomask; 

xinfo .display = dpy; 
xinfo . rmdb = NULL; 
xinf o . appl_id . name = NULL; 
xinfo. appl_id. class = NULL; 
xinfo.args .argc_p = NULL; 
xinfo .args .argv = NULL; 
xinf o . flags .no_monitor = 1; 
xinfo.f lags . force_client_SS = 0; 

infomask = PXPHIGS INFO DISPLAY | PXPHIGS INFO FLAGS NO MON; 
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/* Open Pex */ 

popen_xphigs ( (char*)NULL, PDEF_MEM_SIZE, infomask, &xinfo) , 



/* 

SetupWorkstation 

This routine opens a PHIGS workstation and sets up a Viewport . 
Z buffering is enabled by calling psethlhsrmode. The structure 
edit mode is set to insert elements and the display update state 
is set to PWAIT. 

*/ 

SetupWorkstation (dpy, win) 
Display *dpy; 
Window win; 
{ 

Pconnid_x_drawable conn; 

Pview_rep3 vrep; /* Declare vieporting variables */ 

Pview_map3 map; 

PpointS vrp, cntr; 

Pvec3 vup; 

Pvec3 vpn; 

conn. display = dpy; 
conn.drawable_id = win; 

popen_ws(WS, (Pconnid *) (&conn) , phigs_ws_type_x_drawable) ; /* Open WS */ 

/* Setup viewport parameters */ 

map.proj_type = PTYPE_PARAL; /* Set projection type */ 

map . vp . x_min = 0.0; map . vp . x_max =1.0; / * Set viewport limits ■* / 
map . vp . y_min = 0.0; map . vp . y_max = 1.0; 
map . vp . z_min = 0.0; map . vp . z_max = 1.0; 

map . win . x_min= -1.5; map . win . x_max= 1.5; /* Set window limits */ 
map . win . y_min= -1.5; map . win . y_max= 1.5; 

map.backjplane = -2.0; /* Set the front and back clipping planes */' 

map.f ront_plane = 1.0; 

map.view_jplane = 0.0; /* Set the location of the view plane */ 
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/* Set projection Reference point */ 
/* in VRC space */ 



vrep.xy_clip = PIND_NO_CLIP; /* Turn Viewport clipping off */ 
vrep.back_clip = PIND_NO_CLIP; /* not to be confused with the */ 
vrep.front_clip = PIND_NO_CLIP; /* clipping at the viewplanes S */ 

vrep.clip_limit = map.vp; /* Set Viewport clipping volume = viewport */ 

/* Setup View Reference Coordinates */ 

vrp.x = 0.0; vrp.y = 0.0; vrp.z = 1.0; /* Set View ref point */ 

/* Set view up vector */ 

vup.delta_x = 0.0; vup.delta_y = 1.0; vup.delta_z = 0.0; 

/* Set view plane normal*/ 

vpn.delta_x = 0.0; vpn.delta_y = 0.0; vpn.delta_z = 1.0; 

peval_view_ori_matrix3 (&vrp, &vpn, &vup ? /* Evaluate orient matrix */ 
&PEX_error f vrep.ori_matrix) ; 

SAFE_PEX("peval_view_ori_matrix3") ; /* Check for error status */ 

peval_view_map_matrix3 ( &map, &PEX_error, /* Evaluate map matrix */ 

vrep .map_matrix) ; 

SAFE_PEX("peval_view_map_matrix3") ; /* Check for error status */ 

pset_view_rep3 ( WS, VIEW, &vrep ); /* Set the view representation */ 

pset_edit_mode(PEDIT_INSERT) ; /* Set edit mode to insert elements */ 

pset_disp__upd_st (WS, PDEFER_WAIT, PMODE_NIVE) ; 

/* Set update state to WAIT */ 
/* Enable WS z buffering */ 

pset_hlhsr_mode(WS, PHIGS_HLHSR_MODE_ZBUFF) ; 
} 

/* Make_boxes 

Make_boxes unposts and deletes any old structures that are in structure 
memory (for reset purposes) , sets edit mode to insert elements and then 
defines a polyline cube and a fillarea cube in 3 dimensions. Structures 
POLYBOX and FILLBOX are defined to contain these data elements along with 
color and style attributes to be applied to the data elements. A higher 
level structure DISPLAY STRUCT is defined to include both the POLYBOX and 
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FILLBOX structures and is then posted to the open workstation to be 
displayed. The workstation is then updated to display the objects. The edit 
mode is set to Replace elements in preparation of structure transfomation 
updates caused by dial input . 
*/ 

Make boxes () 



Pmatrix3 identity; 

/* Define polyline cube vectors */ 

static Ppoint3 line_pointsl [] = /* Define points for front face */ 

{{ 0.5, 0.5/ 0.5} , { 1.0, 0.5, 0.5} , 

{ 1.0, 1.0, 0.5} , { 0.5, 1.0, 0.5} , 
{ 0.5, 0.5, 0.5}}; 

static Ppoint3 linej?oints2 []= /* Define points for back face */ 

{{ 0.5, 0.5, 0.0} , { 1.0, 0.5, 0.0} , 

{ 1.0, 1.0, 0.0} , { 0.5, 1.0, 0.0} , 

{ 0.5, 0.5, 0.0}}; 

static Ppoint3 line_points3 []= /* Define connecting line */ 
{{ 0.5, 0.5, 0.5} , { 0.5, 0.5, 0.0}}; 

static Ppoint3 line__points4 []= /* Define connecting line */ 
{{ 1.0, 0.5, 0.5} , { 1.0, 0.5, 0.0}}; 

static Ppoint3 line_points5 []= /* Define connecting line */ 
{{ 1.0, 1.0, 0.5} , { 1.0, 1.0, 0.0}}; 

static Ppoint3 line_points6 []= /* Define connecting line */ 
{{ 0.5, 1.0, 0.5} , { 0.5, 1.0, 0.0}}; 



'/* Define solid cube faces */ 

static Ppoint3 f ill_pointsl [] = /* Define points for front face */ 

{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5) , 

{ 0.0, 0.0, 0.5} , { -0.5, 0.0, 0.5}}; 

static Ppoint3 f ill_points2 []= /* Define points for back face */ 

{{ -0.5, -0.5, 0.0} , { 0.0, -0.5, 0.0} , 

{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 
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static Ppoint3 f ill_points3 []= /* Define points for right face */ 
{{ 0.0, -0.5, 0.5} , { 0.0, -0.5, 0.0} , 
{ 0.0, 0.0, 0.0} , { 0.0, 0.0, 0.5}}; 

static Ppoint3 f ill_j>oints4 []= /* Define points for left face */ 
{{ -0.5, -0.5, 0.5} , { -0.5, -0.5, 0.0} , 
{ -0.5, 0.0, 0.0} , { -0.5, 0.0, 0.5}}; 

static Ppoint3 f ill_points5 [] = /* Define points for bottom face */ 
{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5} , 
{ 0.0, -0.5, 0.0} , { -0.5, -0.5, 0.0}}; 

static Ppoint3 f ill_points6 []= /* Define points for top face */ 
{{ -0.5, 0.0, 0.5} , { 0.0, 0.0, 0.5} , 
{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 

Ppoint_list3 Line_list [5] , Fill_list [5] ; 

pset_edit_mode (PEDIT_INSERT) ; /* Set edit mode to insert elements */ 
punpost_all_structs (WS) ; /* Unpost to remove any old structures */ 
pdel_all_structs () ; /* Delete any old structures */ 

popen_struct (POLYBOX) ; /* Open line drawing structure */ 

pset_line_colr_ind(2) ; /* Assign default index color 2 to lines*/ 

Line_list[0] .num_points = 5; /* Fill in number of points in list */ 
Line_list [0] .points = line_pointsl; /* Pointer to point array */ 
ppolyline3 (&Line_list [0] ) ; /* Create a polyline element */ 

pset_line_colr_ind(3) ; /* Assign default index color 3 to lines*/ 

Line_list [1] .num_points = 5; 
Line_list [1] .points = line_points2; 
ppolyline3 (&Line_list [1] ) ; 

pset__line_colr_ind(4) ; /* Assign default index color 4 to lines*/ 
Line_list [2] .num_jpoints = 2; 
Line_list [2] .points = line_jpoints3; 
ppolyline3 (&Line_list [2] ) ; 

pset_line__colr_ind(5) ; /* Assign default index color 5 to lines*/ 
Line_list [3] .num_points = 2; 
Line_list [3] .points = line_points4; 
ppolyline3 (&Line_list [3] ) ; 
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pset_line_colr_ind(6) ; /* Assign default index color 6 to lines*/ 
Line_list [4] .num_points = 2; 
Line_list [4] .points = line_points5; 
ppolyline3 (&Line_list [4] ) ; 

pset_line_colr_ind(7) ; /* Assign default index color 7 to lines*/ 
Line_list [5] .num__points = 2; 
Line_list [5] .points - line_points6; 
ppolyline3 (&Line_list [5] ) ; 

pclose_struct () ; /* Close line drawing structure */ 

popen_struct (FILLBOX) ; /* Open filled drawing structure */ 
pset_int_style (PSTYLE_SOLID) ; /* Set interior style to be solid */ 
pset_int_colr_ind(7) ; /* Assign default index color 7 to face */ 
Fill_list [0] .num_points = 4; /* Fill in number of points in list */ 
Fill_list[0] .points = f ill_jDointsl; /* Pointer to point array */ 
pfill_area3(&Fill_list [0]) ; /* Create a fill area element */ 

pset_int_colr_ind(3) ; /* Assign default index color 3 to face */ 
Fill__list [1] .numjpoints = 4; 
Fill_list [1] .points = f ill_points2; 
pf ill_area3 (&Fill_list [1] ) ; 

pset_int_colr_ind(2) ; /* Assign default index color 2 to face */ 
Fill_list [2] .num_points = 4; 
Fill__list [2] .points = f ill_points3; 
pf ill_area3 (&Fill_list [2] ) ; 

pset_int_colr_ind(4) ; /* Assign default index color 4 to face */ 
Fill_list [3] .num_points = 4; 
Fill_list [3] .points = f ill_points4; 
pf ill_area3 (&Fill_list [3] ) ; 

pset_int_colr_ind(5) ; /* Assign default index color 5 to face */ 
Fill_list [4] .num_points = 4; 
Fill_list [4] .points = f ill_points5; 
pf ill_area3 (&Fill_list [4] ) ; 

pset_int_colr_ind(6) ; /* Assign default index color 6 to face */ 
Fill_list [5] .num_j?oints = 4; 
Fill_list [5] .points = f ill_jpoints6; 
pf ill_area3 (&Fill_list [5] ) ; 



( 



C 



( 
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pclose_struct () ; 
make_identity (identity) , 



/* Close filled drawing structure */ 



/* Open the top level display structure */ 

*/ 
*/ 
*/ 



popen_struct (DISPLAY_STRUCT) 

pset_view_ind(VIEW) ; /* Set the view index to be used 

pset_hlhsr_id(PHIGS_HLHSR_ID_ON) ; /* Turn on Z buffering 
plabel (TRANS) ; /* Insert a label for future updates 



/* set transformation matrix*/ 

pset_local_tran3 (identity, PTYPE_RE PLACE) ; 

pexec_struct (FILLBOX) ; /* Include the filled square 
pexec_struct (POLYBOX) ; /* Include the line drawn square 
pset_hlhsr_id(PHIGS_HLHSR_ID_OFF) ; /* Turn off Z buffering 

pclose struct () ; 



ppost_struct (WS, DISPLAY_STRUCT, 1.0); /* Post DISPLAY_STRUCT, prio 1 */ 



pupd_ws (WS, PUPD_PERFORM) ; 
pset_edit_mode (PEDIT REPLACE); 



/* Update the workstation */ 
/* Set edit mode to replace */ 



/* 

make__identity 

This routine sets the passed matrix to be an identity matrix. 
*/ 

make_identity (matrix) 
Pmatrix3 matrix; 



matrix [0] [0] = 1 
matrix [0] [1] = 
matrix[0] [2] = 
matrix [0] [3] = 
matrix[l] [0] = 
matrix [1] [1] 
matrix[l] [2] 
matrix [1] [3] 
matrix[2] [0] 
matrix[2] [1] 
matrix[2] [2] 
matrix[2] [3] 
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matrix [3] [0] = 

matrix[3] [1] = 

matrix[3] [2] = 

matrix [3] [3] = 1 



C 



Cleanup () 
{ 

punpost_all_structs (WS) , 

pdel_all_structs () ; 

pclose_ws (WS) ; 

pclose_jphigs () ; 
} 



/* Cleanup routine when done 

/* Unpost all structures on ws 

/* Delete all structures */ 

/* Close workstation */ 

/* Close PHIGS */ 



C 



c 
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headers. h 

/* 

header3 .h 
Contains global header information for example program 3. 

Author: James Buckmiller May 1990. 

Copyright (C) 1990, Evans & Sutherland 

*/ 

#define WS 1 

#define POLYBOX 1 /* define some constants to be used later */ 

#define FILLBOX 2 

#define DISPLAY_STRUCT 3 

tdefine VIEW 4 

#define TRANS 5 

#define SPACEKEYSYM 32 

#define MAXDIALS 8 

#define CHARS_PER_DIAL 8 

#define SAFE_PEX( routine) Error_Check ( FILE , LINE , routine) 

#define DEG_TO_RAD (D) ((3.14159265358 / 180.0) * (D) ) 
#define DIALSCALE .005 /* Dial Scale value */ 

extern Window myWin; 
extern Display *dpy; 
extern char *ProgramName; 

extern Pmatrix3 identity; 

extern Pint PEX_error;/* For PEX error numbers */ 
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@xampls4x 

/* • ' 

example 4. c 

This program incorporates program 3 functionality for model interaction 
with dials as well as keyboard control for reset and exit functions. The 
new functionality added for program 4 is the E&S picking extension to PEX. 
As a model element is picked using mouse button 1 the element is deleted 
from the structure. If an element is picked with either mouse button 2 or 
3 a prepick highlight of the object is performed to visually show the user 
what elements will be picked if a pick were to be performed. To reset the 
picture press the r key on the keyboard. To exit the client press the e key 
on the keyboard. 



Author: James Buckmiller May 1990. 
Modified: J. Buckmiller Mar 1991. 



Approved C binding 



Copyright (C) 1990, Evans & Sutherland 



*/ 

#include <X11/Xlib.h> 

#include <Xll/Xatom.h> 

#include <Xll/extensions/XInput .h> 

#include <X1 1 /phigs /phigs . h> 

#include <Xll/keysymdef .h> 

#include <Xll/extensions/XPick.h> 



C 



#include "header4.h" 



Window myWin; 
Display *dpy; 
char *ProgramName; 
Pint PEX error; 



/* For PEX error numbers */ 



int Major_op, First_ev, First_err; 

Pint_list nset_names; 

Pint namesints [1] ; 

XPickFilter pick_incl, pick_excl; 

PC pc; 



/* pick extension parameters */ 
/* pick list nameset */ 
/* nameset list arrays */ 
/* pick inclusion/exclusion filters */ 
/* pick context */ 



main(argc, argv) 
int argc; 
char *argv[] ; 
{ 



C 
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int i; 

char *geom = NULL; 

char ^display = NULL; 

int winposx, winposy, winwidth, winheight; 

ProgramName = argv[0]; 



winposx = 100; 
winposy = 100; 
winwidth = 600; 
winheight = 600; 



/* default window geometry */ 



for (i=l; i < argc; i++) 

{ 

char *arg = argv[i]; 

if (arg[0] == '-' ) 
{ 
switch (arg[l]) 
{ 
case ' d r : /* -display host:dpy */ 
if (++i >= argc) usage () ; 

display - argvfi]; 
continue; 
case ' g r : /* -geometry host:dpy */ 

if (++i >= argc) usage (); 

geom = argv[i] ; 
continue; 
default : 

usage () ; 
} 
} 



/* Parse the command line */ 



if ( ! (dpy = XOpenDisplay (display) ) ) 



/* Attempt to open the display */ 



perror ("Cannot open display\n") ; 

exit (-1) ; 

} 

if (geom) 
{ /* Generate position and size from the geometry string */ 

(void) XParseGeometry (geom f &winposx, &winposy, &winwidth f &winheight) ; 
} 
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/* Create a simple, unmapped input /output window */ 
myWin = XCreateSimpleWindow (dpy, RootWindow (dpy, Def aultScreen (dpy) ) , 

winposx, winposy, winwidth, winheight, , NULL , NULL ) ; 

/* Change the window name property */ , 

XChangeP rope rty (dpy, myWin, XA_WM_NAME, XA_STRING, 8, PropModeReplace, 
"Example 4: r Key = Reset e Key = Exit", 40); 



/* Map the window for display */ 



XMapWindow (dpy, myWin) ; 



/* Begin PHIGS calls 
StartPhigs (dpy, myWin) ; 



*/ 



/* 

usage 

This routine prints out command line argument information if the user 

supplied arguments are incorrect. 

*/ 



usage () 



/* Print usage message */ 



( 



fprintf (stderr, "usage: %s [-options ...]\n\n", ProgramName) ; 

fprintf (stderr, "where options include : \n") ; 

fprintf (stderr, " -display host: dpy X server to use\n") ; 

fprintf (stderr, " -geometry geom geometry of window\n") , 

fprintf (stderr, "\n") ; 

exit (1); 



/* 

Get_e vents 

This routine is the event handeling routine. First the usual X events are 
trapped. If an expose event occurs then a PHIGS redrawallstructures is 
called. If a Keyboard event occurs the keysym is reviewed to see if it is 
an "e" for exit or an "r" for a reset of the display. If the event that is 
generated is not a usual X event then it is checked to be an extension event 
for dials events or picking events. If dials event then the object is 
transformed. If a picking event then the element picked is deleted from the 
structure listed in the pick info. 
*/ 



C 
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Get_e vents (dpy) 
Display *dpy; 



XDevicelnfo *devices = NULL; 
XDevice *dials = NULL; 
XEventClass DeviceMotionClass [100] ; 
XID dials_id; 
XEvent report; 

XKeyPressedEvent *pev; 
KeySym key; 
char buf [20] ; 

unsigned long event_mask; 
XButtonPressedEvent *bdown; 
XButtonReleasedEvent *bup; 
XPickEvent *pick; 

int knob_totals [MAXDIALS] ; 

Atom dials_atom = 0; 

XStringFeedbackControl strfc; 

int done = , j ; 

KeySym ledst ring [MAXDIALS] [CHARS_PER_DIAL] , blankled [MAXDIALS] ; 

Pmatrix3 composite; 

static Pmatrix3 currmatrix[] = 

{{1,0,0,0}, {0,l,0 r 0}, {0 f r l f 0} f {0 f f f l}}; 

Pvec3 scale, trans; 

int ndevices =0, i, EventCount = 0, DeviceMotion = ~1; 

int rotx=0, roty=0, rotz=0; 

Ppoint3 cntr; 

/* Dial labels */ 
static char text string [MAXDIALS] [CHARS_PER_DIAL] = 

{ " X ROT ", " Y ROT ", " Z ROT " , 
" SCALE ", "X TRAN ", " Y TRAN ", 
" Z TRAN " , " " } ; 

cntr.x =0.0; /* Define center point of transformations */ 

cntr.y = 0.0; 

cntr.z = 0.0; 

scale. delta_x = 1.0; /* Define initial scale to be 1 */ 

scale. delta_y = 1.0; 
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scale. delta_z = 1.0; 

trans. delta_x = 0.0; /* Define initial translation to be */ 

trans .delta_y =0.0; 

trans .delta_z = 0.0; 

/* Determine if picking extension is present */ 
/* Get the opcodes for the errors and events */ 
XQueryExtension (dpy, PICKNAME, &Major_op, &First_ev, &First_err) ; 

/* Get the atom ID for the Knob box */ 
dials_atom = XInternAtom(dpy, "KNOB_BOX", True); 

/* Get list of Input devices */ 

devices = XListlnputDevices (dpy, &ndevices) ; 

/* Find the dials device in the list and open the device */ 
for (i = 0; i < ndevices; i++, devices++) 
if ( (devices->type == dials_atom) && 

(devices->use == IsXExtensionDevice) ) 

{ 

dials_id = devices->id; 

dials = XOpenDevice (dpy, dials_id) ; /* Get Xdevice structure */ 

break; /* for the dials '*/ 

} 

if ('.dials) 

{ 

fprintf (stderr, "?dials box not found in X extension device 

list.\n M ) ; 
exit (1) ; 

} 

/* Get event class values for dials */ 
DeviceMotionNotify (dials, DeviceMotion f DeviceMotionClass [EventCount] ) ; 
EventCount++; 

/* Tell server to pass on Extension events */ 
XSelectExtensionEvent (dpy, my Win f DeviceMotionClass, EventCount); 

/* Set the event mask for the window */ 
XSelect Input (dpy, myWin, ButtonPressMask | ButtonReleaseMask | 

EnterWindowMask | LeaveWindowMask | KeyPressMask | 
ExposureMask) ; 

/* Set the picking mode to return the item picked that is nearest in Z V 
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XSetPickMode (dpy, pc, pick_near) ; 

/* Set the pick box size to 5x5 pixels */ 
XSetPickBoxSize (dpy, pc, 5, 5) ; 

/* Cause all of pickable items to be highlighted */ 
XSetPickHighlightingMode (dpy, pc, pick_highlighting_command) ; 

/* Select pick events to be returned */ 
XSelectPickEvents (dpy f myWin, PickMask) ; 

for (i = 0; i < MAXDIALS; i++) /* Load the keysym arrays */ 

for (j = 0; j < CHARS_PER_DIAL; j++) 
{ 

ledstring[i] [j] = (KeySym) textstring [i] [ j] ; /* Dial labels */ 
blankled[j] = SPACEKEYSYM; /* Blank labels */ 



strfc. class = StringFeedbackClass; 

strfc. length = sizeof (XStringFeedbackControl) ; 

strfc.num_keysyms = CHARS_PER_DIAL; 

for (i=0; KMAXDIALS; i++) /* Set the dial labels upon */ 

{ /* startup of client. */ 

strfc. id = i; 

strfc.syms_to_display = ledstring [i] ; 

XChangeFeedbackControl (dpy, dials, DvString, fistrfc) ; 
} 

while ( !done) 
{ 

XNext Event (dpy, & report ) ; /* Get next event from event queue */ 

if (report. type < LASTEvent) /* Check if extension event or not */ 
{ 

switch (report .type) 
{ 

case EnterNotify: /* Turn on the dial labels */ 

for (i=0; KMAXDIALS; i++) /* when the cursor enters */ 
{ /* the window. */ 

strfc. id = i; 

strfc.syms_to_display = ledstring [i] ; 

XChangeFeedbackControl (dpy, dials, DvString, fistrfc) ; 
} 
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break; 
case KeyPress: /* Trap keyboard events */ 

/* and perform function. */ 
pev = (XKeyP res sedE vent *) & report; 
XLookupString(pev, buf, sizeof (buf ) , &key, NULL); 
if(buf[0] == ' r' ) /* Reset picture */ 

{ 
make_identity (currmatrix) ; /* Currmatrix = identity matrix */ 
Make_boxes () ; /* Rebuild the structures*/ 

/* Reset xformation parameters */ 
scale. delta_x = scale. delta_y = scale. delta_z = 1.0; 
trans ,delta_x = trans ,delta_y = trans .delta_z = 0.0; 
rotx = roty = rotz = 0; 
} 

if (buf [0] == 'e') /* Exit Program */ 

done = 1; 
break; 

case ButtonPress: /* Trap button press */ 

bdown = (XButtonPressedEvent *) & report; 
if (bdown->button == Buttonl) 
{ /* Do pick traversal */ 

XPick(dpy, myWin, pc f bdown->x, bdown->y) ; 
} 

else 
{ /* Do pick highlighting traversal */ 

XPrePick (dpy, myWin, pc, bdown->x, bdown->y) ; 

} 

break; 

case ButtonRelease: /* Redraw to remove prepick highlight */ 
bup = (XButtonReleasedEvent *) Sreport; 
predraw_all_structs(WS, PFLAG_ALWAYS) ; 
break; 

case Expose: /* Expose events = redraw */ 

predraw_all_structs(WS, PFLAG_ALWAYS ) ; 
break; 

case LeaveNotify: /* Blank LEDs when cursor leaves window */ 
for (i=0; KMAXDIALS; i++) 
{ 

strfc.id = i; 
strfc.syms_to_display = blankled; 
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XChangeFeedbackControl (dpy, dials, DvString, &strfc) 
} 
break; 

\ 
/* else it's an extension event */ 



else if (report. type == DeviceMotion) 



/* Dials input */ 



XDeviceMotionEvent *dm = (XDeviceMotionEvent 



& report; 



for (i=0; KMAXDIALS; i++) 
knob totals [i] = 0; 



/* Zero the knob accumulator array */ 



/* 

The following piece of code goes out to the event queue and scoops 
off all dial motion events that are found on the queue with the 
XCheckTypedEvent call. These events are then accumulated for each 
axis and then processed with the acccumulated values. 

The reason for doing this is to increase the performance of the system. If 
an update of the workstation display is performed for every dial event that 
occurs the display will get behind thus causing a lag time between when the 
dials stop sending events and the system finishes unpiling the event queue. 
For this application grabbing all dial events off the queue works well 
however, one must beware that if an application allows the dials to be 
redefined with some other event (function key or pick menu) this method may 
not be the way to get the dial events since there may be keypress or pick 
events intermixed with the dials events. To get around this problem one may 
wish to use the XPeekEvent routine to look ahead one event to be sure that 
it is the same event class as the ones being accumulated. 
*/ 

do /* Collapse the events before processing */ 

for (i=0; i < dm->axes_count; i++) 

knob_totals [dm->f irst_axis+i] += dm->axis_data [i] ; 

/* Gather all dial events from the event queue */ 
while (XCheckTypedEvent (dpy, DeviceMotion, dm) ) ; 

/* Process DeviceMotion events */ 

if (knob_totals [0] ) /* dial 1 input check rot x */ 

rotx += knob_totals [0] ; 

if (knob_totals [1] ) /* Dial 2 input check rot y */ 

roty += knob_totals [1] ; 
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if (knob_totals [2] ) /* Dial 3 input check rot z */ 

rotz += knob_totals [2] ; 

if (knob__totals [3] ) /* Dial 4 input check uniform scale */ 

{ 

scale. delta_x += knob_totals [3] * DIALSCALE; 

scale. delta_y +== knob_totals [3] * DIALSCALE; 

scale. delta_z += knob__totals [3] * DIALSCALE; 
} 

if (knob_totals[4] ) /* Dial 5 input check trans x */ 

trans. delta_x += knob__totals [4] * DIALSCALE; 

if (knob_totals [5] ) /* Dial 6 input check trans y */ 

trans. delta_y += knob__totals [5] * DIALSCALE; 

if (knob_totals [6] ) /* Dial 7 input check trans z */ 

t rans.de It a__z += knob_totals [6] * DIALSCALE; 

/* Build the transformation matrix */ 
pbuild_tran_matrix3 (ficntr, &trans, DEG_TO_RAD (rotx) , DEG_TO_RAD (roty) 
, DEG_TO_RAD ( rot z ) f &scale f &PEX_error 
r currmatrix) ; 
SAFE_PEX("pbuild_tran_matrix3") ; /* Check for error status */ 

/* Combine old and new matrices */ 
popen_struct (DISPLAY_STRUCT) ; /* Open structure for editing */ 

{ 

pset_elem_ptr (0) ; /* Reset element pointer */ 

pset_elem_ptr__label (TRANS) ; /* Find transformation label */ 
pof f set_elem_ptr (1) ; /* Point at matrix */ 

/* replace matrix */ 
pset_local_tran3 (currmatrix, PTYPE_PRECONCAT) ; 
} 
pclose_struct () ; /* Close structure */ 

predraw_all_structs(WS, PFLAG_ALWAYS) ; /* Redraw the structure */ 

} 
else if (report. type == First_ev + XPickEventOf f set) /* Pick event */ 
{ /****** picking event ******/ 
/*_ „„ .„_„..—-„„.„„.„„„„——„„ 

The picking extension returns a structure that contains 
information about what element and structure was picked, 
where in screen space or model space the pick occured 
and other usefull information, (see pg 3-4 X Picking Extension 
document) . For this example we are only using the structure 
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number and element number to position the 
in preparation for a delete element PHIGS 



element pointer 
call. 



-*/ 



pick = (XPickEvent *) & report; 

popen_struct (pick->structureid) ; 

pset_elem_ptr (0) ; 

pof f set_elem_ptr (pick->elementid) , 

pdel_elem() ; 

pclose_struct () ; 

pupd_ws (WS,PUPD PERFORM) ; 



/' 



/* Open structure returned */ 

/* by pick */ 

/* Go to picked element */ 

/* Delete the element */ 

/* Close the structure */ 

/* Cause an update of WS */ 
to show element removed*/ 



} 
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motif4.c 

/* 

m o t i f 4 . c 

This program expands on motif 3 to include picking of PEX structures. 
Picking is accomplished via the Evans & Sutherland picking extension to X. 
Structure elements can be picked via the mouse buttons. Button 1 will 
delete the picked element, while buttons 2 or 3 will highlight the picked 
element while the button is held down. 

Reset and quit push buttons are provided as in motif 3. When the reset 
button is pushed, the structures are restored to their original pristine 
state. 

Author: Rich Thomson 

Date: Thursday, June 12th, 1990 

Modified: J. Buckmiller Mar 1991. Approved C binding 



C 



Copyright (C) 1990, Evans & Sutherland Computer Corporation 



*/ 



#include <X11/Xlib.h> 
#include <Xll/extensions/XInput .h> 
#include <Xll/extensions/XPick.h> 
#include <Xll/phigs/phigs .h> 
#include <X11/Intrinsic.h> 
#include <Xm/RowColumn.h> 
#include <Xm/PushBG.h> 
#include <Xm/DrawingA.h> 

#include "header4.h" 



C 



Display *dpy; /* Xll display connection */ 

char *ProgramName; 

int DeviceMotion; /* device motion event type */ 

Window drawWindow; /* drawing window */ 

Pint PEX_error; /* For PEX error numbers */ 

int Major_op, First_ev, First_err; /* pick extension parameters */ 
Pint_list nset_names; /* pick list nameset */ 

Pint namesints [1] ; /* nameset list arrays */ 

XPickFilter pick_incl, pick_excl;/* pick inclusion/exclusion filters */ 
PC pc; /* pick context */ 

static XDevice *dials = NULL; /* dials device */ f 
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static Pmatrix3 currmatrix = { { 1, 0, 0, } , { 0, 1, 0, } , { 0, 0, 1, } , { 0, 0, 0, 1 } } ; 

static Boolean done = False; 

static Pvec3 scale = { 1.0, 1.0, 1.0 }; 

static Pvec3 trans = { 0.0, 0.0, 0.0 }; 

static int rotx = 0, roty = 0, rotz = 0; 

/* 

quit_CB 

The callback procedure for the quit pushbutton widget. It simply sets the 

event processing exit flag to True, which will cause Get_events to stop 

processing events. 

*/ 

void quit_CB(quitButton, client_data, call_data) 

Widget quitButton; 

caddr_t client_data; 

XmAnyCallbackStruct *call_data; 
{ 

XmCR ACTIVATE) 



} 


if 


(call_ 
done = 


_data->rea 
= True; 


son 


/* 










reset 


CB 







The callback procedure for the reset button. It re-initializes the 
parameters that define the transformation matrix corresponding to 
translate, rotate and scale operations. The posted structures are also 
re-initialized since picking elements could have caused some elements to 
be deleted. 

*/ 

void reset_CB(resetButton, client_data, call_data) 
Widget resetButton; 
caddr_t client_data; 
XmAnyCallbackStruct *call_data; 
{ 

if (call_data->reason == XmCR_ACTIVATE) 
{ 

Make_boxes ( ) ; 

/* reset xformation parameters */ 
scale. delta_x = scale. delta_y = scale .delta_z = 1.0; 
trans .delta_x = trans .delta_y = trans .delta_z = 0.0; 
rotx = roty = rotz = 0; 
} 
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_ 

drawArea_CB ^- 

The callback procedure for the drawing area widget. It redraws all 
the structures on the workstation. 

*/ 

void drawArea_CB (drawArea, client_data, call_data) 
Widget drawArea; 
caddr_t client_data; 
XmDrawingAreaCallbackStruct *call_data; 

{ 

if (call_data->reason == XmCR_EXPOSE) 

predraw_all_structs (WS, PFLAG_ALWAYS) ; 

} 

/* 

pick__CB 

This routine performs the picking operation on the structures drawn in 
the drawing area widget „ 

When a ButtonPress event is received, a pick operation is performed if 

the user pressed Buttonl. The pick operation will cause picking events ^ 

to be generated for any objects selected. If the user pressed some ^ 

button other than Buttonl, a pre-pick operation is performed, which will 

highlight the object selected. The pick operations are performed at the 

device (pixel) coordinates where the button press took place. 

When a ButtonRelease event is received, all structures posted to the 
workstation are redrawn. This will cause deleted structure elements to 
be visually reflected on the screen (for Buttonl) as well as remove 
highlighting caused by other mouse buttons. 

*/ 

void pick_CB (drawArea, client_data, call_data) 
Widget drawArea; 
caddr__t client_data; 
XmDrawingAreaCallbackStruct *call_data; 

{ 

XButtonPressedEvent *bpress = (XButtonPressedEvent *) call_data->event; 

if (call_data->reason == XmCRJENPUT) 

{ 

switch (call__data->event->type) 

{ 

case ButtonPress: m 
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if (bpress->button == Buttonl) 

XPick(dpy, call_data->window, pc, bpress->x, bpress->y) ; 
else 

XPrePick (dpy, call_data->window, pc, bpress->x, bpress->y) , 
break; 

case ButtonRelease: 

predraw_all_structs (WS, PFLAG_ALWAYS) ; 

break; 
} 



/* 

knob_labels 

This array holds the KeySym' s that contain the knob labels. It is used by 
the enter and leave window handlers to blank out the labels when the 
pointer is not in the drawing area window. 

Dial labels are CHARS_PER_DIAL KeySyms per dial. Ascii characters can be 

converted to KeySyms by C type casting. 

*/ 

static KeySym knob__labels [MAXDIALS] [CHARS_PER_DIAL] ; 

/* 

enter_handler 

This event handler restores the knob labels to our labels when the 
pointer moves into the drawing window. Conditionally labelling the dials 
in this way gives extra feedback to the user that the dials are active 
only when the mouse is inside the appropriate window. 

*/ 

void enter_handler (widget, client_data, event, continue_to_dispatch) 
Widget widget ; 
caddr_t client_data; 
XEvent *event; 

Boolean *continue_to_dispatch; 
{ 

register int i; 
XStringFeedbackControl strfc; 

strfc. class = StringFeedbackClass; 

/* initialize the feedback structure */ 
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strfc. length = sizeof (XStringFeedbackControl) ; 
strfc.num_keysyms = CHARS_PER_DIAL; 

for (i = 0; i < MAXDIALS; i++) /* change each dial */ 
{ 

strfc. id = i; /* id is the knob to change */ 
strfc. syms_to_di splay = knob_labels [i] ; 
XChangeFeedbackControl (dpy, dials, DvString, &strfc) ; 
} 
} 

/* 

leave_handler 

This event handler blanks the knob labels when the pointer leaves the 
drawing window. 

*/ 

void leave_handler (widget, client_data, event, continue_to_dispatch) 
Widget widget ; 
caddr_t client_data; 
XEvent *event; 
Boolean *continue_to_dispatch; 



C 



{ 



static XStringFeedbackControl strfc; 
static KeySym blanks [CHARS_PER_DIAL] ; 
static Boolean initialized = Falser- 
register int i; 

if (Unitialized) /* initialize variables the first */ 

/* time we're called */ 
{ 

for (i = 0; i < CHARS_PER_DIAL; i++) 

blanks [i] = (KeySym) ' ';/* prepare a blank keysym array */ 

strfc. class = StringFeedbackClass; /*initialize the feedback struct*/ 
strfc. length = sizeof (XStringFeedbackControl) ; 
strfc.num_keysyms = CHARS_PER_DIAL; 
strfc. syms_to_display = blanks; 

initialized = True;/* remember we've been initialized */ 
} 

for (i =0; i < MAXDIALS; i++) /* for each dial */ 



C 



( 
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strfc.id = i;/* indicate which dial to change */ 

/* change it */ 
XChangeFeedbackControl (dpy, dials, DvString, fistrfc) ; 
} 



/* 

open_knob 

This routine opens the knob box on the given display and selects device 
motion extension events on the given window. Extension events are 
selected by first invoking the appropriate macro on an XEventClass 
structure (in this case DeviceMotionNotify) and then calling 
XSelectExtensionEvent . 
*/ 

void open_knob ( ) 
{ 

/* dial labels as ascii strings */ 
static char textstring [MAXDIALS] [CHARS_PER_DIAL] = { 
" X ROT ", " Y ROT ", " Z ROT "," SCALE ", 

" X TRAN ", " Y TRAN ", " Z TRAN ", " " /* eighth label is blank */ 
}; 
register int knob, i; 

int ndevices; /* number of extension devices */ 
XDevicelnfo ^devices = NULL;/* extension device info list */ 
Atom dials_atom = XInternAtom(dpy, "KNOB_BOX", True) ; 

/* intern device name into an atom */ 
XID dials_id; /* device ID for dials box */ 
XEventClass eventClass [1] ; 

devices = XListlnputDevices (dpy, &ndevices) ; /* get list of devices */ 

for (i = 0; i < ndevices; i++, devices++) 

if ( (devices->type == dials_atom) && (devices->use == 

IsXExtensionDevice) ) 
{ /* did we find the dial box? */ 

dials_id = devices->id; /* yes, remember its device ID */ 
dials = XOpenDevice (dpy, dials_id) ; /* and open it */ 
break; /* we only want the first one... */ 



if (Jdials) /* couldn't open or find dials */ 
{ 

fprintf (stderr, "?couldn't open dials box.\n"); 
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exit(l); I 

} ^ 

■/* select device motion events */ 
DeviceMot ionNot if y (dials, DeviceMot ion, eventClass [0] ) ; 
XSelectExtensionEvent (dpy, drawWindow, eventClass, 1) ; 

for (knob = 0; knob < MAXDIALS; knob++) 

/* convert ascii labels to KeySyms */ 

for (i - 0; i < CHARS_PER_DIAL; i++) 

knob labels [knob] [i] = (KeySym) textstring[knob] [i] ; 



/* 

init_pick 

This routine initializes the picking extension. It must be called after 
the pick context is established (in routine SetupWorkstation, file 
phigs4.c)and before event processing is begun. 

Major_op is the major opcode of the picking extension. First_ev is the ^ 
first event number dynamically allocated for the extension. First_err is 
the first error number dynamically allocated for the extension. 

*/ 

void initjpick () 

{ /* query picking extension */ 

/* for major opcode, first event */ 
XQueryExtension(dpy, PICKNAME, &Major__op, &First_ev, &First_err) ; 

/* Set the picking mode to return */ 
/* the item picked that is nearest */ 
XSetPickMode(dpy, pc, pick_near) ; /* in Z */ 

XSetPickBoxSize (dpy, pc, 5, 5);/* Set pick box size to 5x5 pixels */ 

/* Cause all of picked item to be */ 

/* highlighted */ 
XSetPickHighlightingMode(dpy, pc, pick__highlighting_command) ; 

/* Select pick and pick path events */ 

/* to be returned */ 
XSelectPickEvents (dpy, drawWindow, PickMask) ; 



( 



/* 

main 



C 
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The main routine creates the widget hierarchy for the program, opens the 
knob box and then calls StartPhigs. StartPhigs will then call Get_events 
to initiate event processing. 

The widget hierarchy used here is: 

motif4 (class topLevelShell) 
I 

+— rowcol (class RowColumn) 
I 

+ drawArea (class DrawingArea) 

i 

+ reset (class PushButtonGadget) 

I 

+ quit (class PushButtonGadget) 

The row column widget is used for organizing its child widgets into a 
columnar layout. The drawing area widget is used for PEX operations and 
the PEX workstation is opened on its window. The two push buttons are 
used to supply reset and quit operations. 

Any necessary resources for the widgets are specified here in the 
program, which override any user defaults or command-line options. Note 
that this is not very friendly to the user who may want to change the 
font of the push buttons. A friendlier way is to provide an application 
defaults file which the user may override with user defaults or 
command-line arguments. For simplicity, I have set the arguments here 
directly. 

The display connection (dpy) and window ID (drawWindow) of the drawing 
area widget are available after the widget hierarchy has been realized. 

BEWARE! '! BEWARE! ! 

The drawing area widget in Motif 1.0 has a bug in that it ignores 
height and width resources supplied at creation time. A workaround 
I've found is to set the margins of the drawing area to be half the 
desired height and width. Since the margins specify the boundary 
between the drawing area widget's border and any children of the 
drawing area widget (we have none here) , the drawing area widget will 
be sized to contain its children plus twice the margins in each 
direction. Hence to get a 600x600 drawing area widget, you can set the 
margins to 300. Other workarounds suggested involve creating the 
drawing area widget as a child of other widgets, but where there are no 
children of the drawing area, I prefer setting the margins. 

*/ 

main(argc, argv) 
int argc; 
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char *argv [] ; 
{ 

Arg args [10] ; 

register int n; 

Widget topLevel, rowColumn, quitButton, resetButton, drawArea; 

XFontStruct *buttonFont; 

XmFontList fontList; 

ProgramName = argv[0]; 

/* create topLevelShell */ 
topLevel = Xtlnitialize (ProgramName, "Example", NULL, 0, &argc, argv) ; 

n = 0; /* window title is a regular string */ 

XtSetArg(args [n] , XmNtitle, "Example 4"); n++; 
XtSetValues (topLevel, args, n) ; 

buttonFont = /* find the font we want for buttons */ 

XLoadQueryFont (XtDisplay (topLevel) , "-*-Helvetica-Bold-R-Normal — 
14*"); 

if (buttonFont) 

fontList = XmFontListCreate (buttonFont, XmSTRING_DEFAULT_CHARSET) ; 

rowColumn = /* create the row column for layout */ 

XtCreateManagedWidget ("rowcol", xmRowColumnWidgetClass, topLevel, 
NULL, 0); 

n = 0; /* create the drawing area for PEX */ 

XtSetArg(args [n] , XmNmarginWidth, 300); n++; /* size appropriately */ 
XtSetArg(args [n] , XmNmarginHeight, 300); n++; 

drawArea = XtCreateManagedWidget ("drawArea", xmDrawingAreaWidgetClass, 
rowColumn, args, n) ; 

/* add exposure and input callbacks */ 
XtAddCallback (drawArea, XmNexposeCallback, drawArea_CB, NULL); 
XtAddCallback (drawArea, XmNinputCallback, pick_CB, NULL) ; 

/* these event handlers take care */■ 
/* of blanking and restoring the */ 
/* dial labels */ 
XtAddEventHandler (drawArea, EnterWindowMask, False, enter_handler, 

NULL) ; 
XtAddEventHandler (drawArea, LeaveWindowMask, False, leave_handler, 

NULL) ; 
n = 0; /* create the reset button */ 
XtSetArg (args [n] , XmNlabelString, 

XmStringCreate ("Click here to reset the picture.", 
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XmSTRING_DEFAULT_CHARSET) ) ; n++; 
if (buttonFont) 
{ 

XtSetArg(args [n] , XmNf ontList, fontList) ; n++; 
} 
resetButton = XtCreateManagedWidget ("reset", xmPushButtonGadgetClass, 
rowColumn, args, n) ; 
/* add an activation callback */ 
XtAddCallback (resetButton, XmNactivateCallback, reset_CB, NULL); 

n = 0; /* create the quit button */ 
XtSetArg(args[n] , XmNalignment, XmALIGNMENT_CENTER) ; 
XtSetArg(args [n] , XmNlabelString, 

XmStringCreate ("Click here to quit the program.", 
XmSTRING_DEFAULT_CHARSET) ) ; n++; 
if (buttonFont) 
{ 

XtSetArg(args [n] , XmNfontList, fontList); n++; 
} 
quitButton = 

XtCreateManagedWidget ("quit", xmPushButtonGadget Class, rowColumn, 
args, n) ; 

/* add an activation callback */ 
XtAddCallback (quitButton, XmNactivateCallback, quit_CB, NULL) ; 

XtRealizeWidget (topLevel) ; /* realize widget hierarchy */ 

dpy = XtDisplay (drawArea) ; /* get the display connection */ 
drawWindow = Xt Window (drawArea) ; /* get the d.a. widget's window ID */ 

open_knob(); /* open the knob box */ 

StartPhigs (dpy, drawWindow);/* Begin PHIGS calls */ 



/* 

Get_e vents 

This routine processes events requested by the program. XtNextEvent 
obtains the next event from the input queue and places it in report. The 
type of the event is then examined to determine if it is an extension 
event or a regular X event. The constant LASTEvent (defined in X.h) is 
bigger than the event type of any X event and can be used to 
differentiate extension events from normal X events. 
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Regular events are handled by the toolkit dispatch mechanism via 
XtDispatchEvent. Extension events (DeviceMotion and picking events) are 
hanlded on a case-by-case basis. 

When a DeviceMotion event is encountered, all device motion events are 
removed from the event queue and accumulated into knob_totals, since the 
dials box reports relative changes . Event explosion is a very real 
possibility since every device motion event requires 2 XEvent structures 
(only 6 axes' worth of data fit in a single XEvent) and the sample rate 
of the dials box is high. Since this program is only concerned with 
cumulative changes in the dials values , it is safe to condense the device 
motion events via XCheckTypedEvent . Since XCheckTypedEvent can remove 
events that are not at the head of the event queue, it may not be 
appropriate for situations where the semantics of a device motion event 
can be changed by another event (for instance, a key or button press) . 

When a pick event is encountered, the picked structure element is deleted 

from the structure and the workstation is updated. 

*/ 

Get_e vents (dpy) 

Display *dpy; 
{ 

XEvent report; 

int i ; 

PpointS cntr; 



C 



C 



cntr.x = 0.0; 
cntr.y = 0.0; 
cntr.z = 0.0; 
scale.delta__x = 1.0 
scale. delta_y =1.0 
scale. delta_z = 1.0 
trans .delta_x =0.0 
trans .delta_y =0.0 
trans. delta z = 0.0 



/* center point of transformations */ 
/* is the origin */ 

/* initial scale is 1 */ 



/* initial translation is */ 



pset_edit_mode (PEDIT_REPLACE) ; /* Set edit mode to replace elements */ 

init_jpick ( ) ; /* initialize picking */ 

while (!done) /* until user wants to quit... */ 
{ 

XtNextEvent (& report ) ;/* get the next event */ 



if (report. type < LASTEvent) 
XtDispatchEvent (& report) ; 



C 
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else if (report. type == DeviceMotion) /* handle device motion event */ 
{ 

XDeviceMotionEvent *dm = (XDeviceMotionEvent *) & report; 

int knob_totals [8] ; 

for (i = 0; i < MAXDIALS; i++ 

/* Initialize knob values array */ 
knob_totals [i] = 0; 

do /* Compress motion events */ 

for (i = 0; i < dm->axes_count; i++) 

knob_totals [dm->f irst__axis+i] +- dm->axis_data [i] ; 
while (XCheckTypedEvent (dpy, DeviceMotion,, dm) ) ; 

/* Process device motion events */ 
if (knob_totals[0] ) /* dial 1 input check rot x */ 

rotx += knob_totals [0] ; 

if (knob_totals[l] ) /* Dial 2 input check rot y */ 

roty += knob_totals [1] ; 

if (knob_totals[2] ) /* Dial 3 input check rot z */ 

rotz += knob_totals [2] ; 

if (knob_totals[3] ) /* Dial 4 input check uniform scale */ 

{ 

scale. delta_x += knob_totals [3] * DIALSCALE; 

scale. delta_y += knob_totals [3] * DIALSCALE; 

scale. delta_z += knob_totals [3] * DIALSCALE; 
} 

if (knob_totals[4]) /* Dial 5 input check trans x */ 

trans. delta_x += knob_totals [4] * DIALSCALE; 

if (knob_totals[5] ) /* Dial 6 input check trans y */ 

trans. delta_y += knob_totals [5] * DIALSCALE; 

if (knob_totals[6] ) /* Dial 7 input check trans z */ 

trans. delta_z += knob_totals [6] * DIALSCALE; 

/* Build the transformation matrix */ 
pbuild_tran__matrix3 (&cntr, Strans, DEG_TO_RAD (rotx) , 

DEG_TO_RAD(roty) , DEG_TO_RAD (rotz) , &scale, &PEX_error f 
currmatrix) ; 

SAFE_PEX("pbuild_tran_matrix3") ; /* Check for error status */ 
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/ * Combine old and new matrices * / | 
popen_struct (DISPLAY_STRUCT) ; /* Open structure for editing */ V 

{ 

pset_elem_ptr (0) ; /* Reset element pointer */ 

pset_elem_j>tr_label (TRANS) ; /* Find transformation label */ 

poffset_elemj?tr(l) ; /* Point at matrix */ 

/* replace matrix */ 

pset_local_trah3(currmatrix, PTYPE_PRECONCAT) ; 

} 

pclose_struct() ; /* Close structure */ 

predraw_all_structs(WS, PFLAG_ALWAYS) ; /* Redraw the structure */ 

} 
else if (report. type == First_ev + XPickEventOf f set) 

/* picking event */ 

{ 

XPickEvent *pick = (XPickEvent *) & report; 

popen_struct (pick->structureid) ; /* open picked structure */ 

{ 

pset_elemj?tr (0) ;/* reset the element points */ 
pof f set_elem_ptr (pick->elementid) ; 

/* set the element pointer to */ 
/* the picked element */ 
pdel_elem(); /* delete the picked element */ 

} 

pclose_struct () ; 

pupd_ws(WS, PUPD_PERFORM) ;/* Cause an update */ 
} 
} 



C 



C 
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phigs4.c 

/* 

phigs4 .c 
This file contains the PHIGS specific routines for the example program4 . 

Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990, Evans & Sutherland 

*/ 

#include <X11/Xlib.h> 
#include <Xll/phigs/phigs .h> 
#include <Xll/extensions/XPick.h> 

#include "header 4. h" 



/* 

Error_Check 

This routine checks the global variable used to store error codes 
returned from PEX. If the error code is non-zero, it prints out a 
diagnostic message and dies. 
*/ 

void Error_Check(File, Line, Routine) 
char *File, ^Routine; 
int Line; 
{ 

if (PEX_error) 
{ 

fprintf (stderr, "(file %s; line %d):\n", File, Line); 
fprintf (stderr, "\t?unexpected PEX error %d in routine %s\n", 

PEX_error, Routine) ; 
exit (1) ; 
} 
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/* 

StartPhigs 

This routine is the top level routine that calls all supporting 
routines in the logical order of a usual phigs routine ie 
open PEX, setup the workstation parameters, define the phigs 
structure and then go into the event loop. 

*/ 

StartPhigs (dpy p win) /* Routine to start phigs calls */ 
Display *dpy; 
Window win; 

{ 

OpenPex (dpy) ; /* Open PEX */ 

SetupWorkstation(dpy, win); /* Setup PHIGS workstation parameters */ 

Make_boxes ( ) ; /* Create Phigs structures */ 

Get_events (dpy) ; /* Event loop */ 

Cleanup (); /* Cleanup phigs structures close workstation */ 

} 



/* 

OpenPex 

This routine Opens PEX on the display that was passed as an argument. 
*/ 

OpenPex (dpy) 
Display *dpy; 
{ 

Pxphigs__info xinfo; 

unsigned long infomask; 

xinfo. display = dpy; 
xinfo. rmdb = NULL; 
xinfo.appl_id.name = NULL; 
xinfo. appl__id. class - NULL; 
xinfo.args.argc_p = NULL; 
xinfo. args.argv = NULL; 
xinfo.f lags .no__monitor =1; 
xinfo.f lags ,force__client_SS = 0; 

infomask = PXPHIGS_INFO_DISPLAY | PXPHIGS_INFO__FLAGS_NO__MON; 

/* Open Pex */ f 
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popen_xphigs( (char*) NULL, PDEF_MEM_SIZE, infomask, &xinfo) ; 
} 

./* 

SetupWorkstation 

This routine opens a PHIGS workstation and sets up a Viewport. 

The structure edit mode is set to insert elements and the display 

update state is set to PWAIT. 

Z buffering is enabled by calling psethlhsrmode 

The nameset list is then filled with the name PICKABLE. This list is 

used to set the picking inclusion filter. This same list will be used 

in the addname set call in Make_boxes to add the PICKABLE name to the 

structure. The UNPICKABLE name is listed in the exclusion filter but 

is not included in any display structures, thus nothing is excluded from 

being picked in this example. 

*/ 

SetupWorkstation (dpy, win) 
Display *dpy; 
Window win; 
{ 

Pconnid_x_drawable conn; 

Pview_rep3 vrep; /* Declare viewporting variables */ 

Pview_map3 map; 

PpointS vrp, cntr; 

PvecS vup; 

Pvec3 vpn; 

conn. display = dpy; 
conn.drawable_id = win; 

/* Open WS */ 
popen_ws(WS, (Pconnid *) (&conn) f phigs_ws_type_x_drawable) ; 

/* Setup viewport parameters */ 

map.proj_type = PTYPE_PARAL; /* Set projection type */ 

map.vp.x_min = 0.0; map . vp . x_max = 1.0; /* Set viewport limits */ 
map . vp . y_min = 0.0; map . vp . y_max = 1.0; 
map . vp . z_min = 0.0; map . vp . z_max = 1.0; 

map . win . x_min = -1.5; map . win . x_max =1.5; /* Set window limits */ 
map . win . y_min = -1.5; map . win . y_max = 1.5; 
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map . back_j>lane = -2.0; /* Set the front and back clipping planes */ 

map. f ront_plane = 1.0; 

map.view_jplane = 0.0; /* Set the location of the view plane */ 



map. pro j_ref_point .x =0.0 
map.proj_ref_point .y =0.0 
map.proj_ref_point .z =3.0 



/* Set projection Reference point */ 
/* in VRC space */ 



vrep.xy_clip = PIND_NO_CLIP; /* Turn Viewport clipping off */ 

vrep.back_clip = PIND_NO_CLIP; /* not to be confused with the */ 
vrep.front_clip = PIND_NO_CLIP; /* clipping at the viewplanes ! */ 

vrep.clip_limit = map.vp; /* Set Viewport clipping volume = viewport */ 

/* Setup View Reference Coordinates */ 

vrp.x = 0.0; vrp.y = 0.0; vrp.z = 1.0; /* Set View ref point */■■ 

/* Set view up vector */ 
vup.delta_x = 0.0; vup.delta_y = 1.0; vup.delta_z = 0.0; 

/* Set view plane normal*/ 
vpn.delta_x = 0.0; vpn.delta_y = 0.0; vpn.delta_z = 1.0; 

peval_view_ori_matrix3 (&vrp, &vpn, &vup, /* Evaluate orient matrix */ i 
&PEX_error, vrep. ori__matrix) ; V^ 

SAFE_PEX("peval_view_ori_matrix3") ; /* Check for error status */ 

peval_view_map_matrix3 ( &map, &PEX_error, /* Evaluate map matrix */ 

vrep.map_matrix) ; 

SAFE_PEX("peval_view_map_matrix3 M ) ; /* Check for error status */ 

pset_view_rep3 ( WS f VIEW, &vrep ); /* Set the view representation */ 

pset_edit_mode (PEDIT_INSERT) ; /* Set edit mode to insert elements */ 
pset_disp_upd_st (WS, PDEFER_WAIT, PMODE_NIVE) ; 

/* Set update state to WAIT */ 

pset_hlhsr_mode(l, PHIGS_HLHSR_MODE_ZBUFF) ;/* Enable WS Z buffering */ 



nset_names.num_ints = 1; /* Name set list count */ 

nset_names.ints = namesints; /* .'Name set list of integers */ 

namesints[0] = PICKABLE; /* Put the PICKABLE name in */ 
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/* the name set list. */ 
pick_incl. number =1; /* Set Picking inclusion filter to 1 name */ 
pick_iricl. integers = namesints; 

/* Set the names list to be same as nameset*/ 

pick_excl. number =0; /* Empty picking exclusion filter */ 
pick_excl. integers = NULL; 

XCreatePC(dpy, pick_PEX, &pc) ; /* Create picking context */ 

XSetPickFilters (dpy, pc, &pick_incl, &pick_excl) ; /* Set pick filters */ 



/* 

Make_boxes 

make_boxes defines a polyline cube and a fillarea cube in 3 
dimensions. Structures POLYBOX and FILLBOX are defined to contain 
these data elements along with color and style attributes to be applied 
to the data elements. A higher level structure DISPLAY_STRUCT is defined 
to include both the POLYBOX and FILLBOX structures and is then 
posted to the open workstation to be displayed. 
*/ 

Make_boxes () 

{ 

Pmatrix3 identity; 

/* Define polyline cube vectors */ 

static Ppoint3 line_jpointsl [] = /* Define points for front face */ 
{{ 0.5, 0.5, 0.5} , { 1.0, 0.5, 0.5} , 

{ 1.0, 1.0, 0.5} , { 0.5, 1.0, 0.5} , 

{ 0.5, 0.5, 0.5}}; 

static Ppoint3 line_points2 [] = /* Define points for back face */ 

{{ 0.5, 0.5, 0.0} , { 1.0, 0.5, 0.0} , 

{ 1.0, 1.0, 0.0} , { 0.5, 1.0, 0.0} , 

{ 0.5, 0.5, 0.0}}; 

static Ppoint3 line_points3 []= /* Define connecting line */ 
{{ 0.5, 0.5, 0.5} , { 0.5, 0.5, 0.0}}; 

static Ppoint3 line_points4 []= /* Define connecting line */ 
{{ 1.0, 0.5, 0.5} , { 1.0, 0.5, 0.0}}; 
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static Ppoint3 line_jpoints5 []= /* Define connecting line */ 
{{ 1.0, 1.0, 0.5} , { 1.0, 1.0, 0.0}}; 

static PpointS line_points6 []= /* Define connecting line */' 
{{ 0.5, 1.0, 0.5} , { 0.5, 1.0, 0.0}}; 

/* Define solid cube faces */ 

static PpointS f ill_jx>intsl []= /* Define points for front face */ 
{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5} , 
{ 0.0, 0.0, 0.5} , { -0.5, 0.0, 0.5}}; 

static PpointS f ill__points2 []= /* Define points for back face */ 
{{ -0.5, -0.5, 0.0} , { 0.0, -0.5, 0.0} , 
{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 

static PpointS f ill_points3 []= /* Define points for right face */ 
{{ 0.0, -0.5, 0.5} , { 0.0, -0.5, 0.0} , 
{ 0.0, 0.0, 0.0} , { 0.0, 0.0, 0.5}}; 

static PpointS f ill_points4 [] = /* Define points for left face */ 
{{ -0.5, -0.5, 0.5} , { -0.5, -0.5, 0.0} , 
{ -0.5, 0.0, 0.0} , { -0.5, 0.0, 0.5}}; 

static PpointS f ill_points5 []== /* Define points for bottom face */ 
{{ -0.5, -0.5, 0.5} , { 0.0, -0.5, 0.5} , 
{ 0.0, -0.5, 0.0} , { -0.5, -0.5, 0.0}}; 

static PpointS f ill_jpoints6 [] = /* Define points for top face */ 
{{ -0.5, 0.0, 0.5} , { 0.0, 0.0, 0.5} , 
{ 0.0, 0.0, 0.0} , { -0.5, 0.0, 0.0}}; 

Ppoint__list3 Line_list [5], Fill_list [5] ; 

pset__edit_mode(PEDIT_INSERT) ; /* Set edit mode to insert elements */ 
punpost_all__structs (WS) ; /* Unpost to remove any old structures */ 
pdel_all_structs () ; /* Delete any old structures */ 

popen_struct (POLYBOX) ; /* Open line drawing structure */ 
pset__line_colr__ind(2) ; /* Assign default index color 2 to lines*/ 
Line_list[0] .numjpoints = 5; /* Fill in number of points in 
list */ 
Line__list [0] .points = line_pointsl; /* Pointer to point array */ 
ppolyline3(&Line_list [0]) ; /* Create a polyline element */ 
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pset_line_colr_ind(3) ; /* Assign default index color 3 to lines */ 

Line_list [1] .num_points = 5; 
Line_list [1] .points = line_j>oints2; 
ppolyline3 (&Line__list [1] ) ; 

pset_line_colr_ind(4) ; /* Assign default index color 4 to lines */ 
Line_list [2] .num_points = 2; 
Line_list [2] .points = line_j>oints3; 
ppolyline3 (&Line_list [2] ) ; 

pset_line_colr_ind(5) ; /* Assign default index color 5 to lines */ 
Line_list [3] .num__points = 2; 
Line_list [3] .points = line_points4; 
ppolyline3 (&Line_list [3] ) ; 

pset_line_colr_ind(6) ; /* Assign default index color 6 to lines */ 
Line_list [4] .num_points = 2; 
Line_list [4] .points = line_points5; 
ppolyline3 (&Line_list [4] ) ; 

pset_line_colr_ind(7) ; /* Assign default index color 7 to lines */ 
Line_list [5] .numjpoints = 2; 
Line_list [5] .points = line_points6; 
ppolyline3 (&Line_list [5] ) ; 

pclose_struct () ; /* Close line drawing structure */ 

popen_struct (FILLBOX) ; /* Open filled drawing structure */ 
pset_int_style(PSTYLE_SOLID) ; /* Set interior style to be solid */ 
pset_int_colr_ind(7) ; /* Assign default index color 7 to face */ 
Fill_list [0] .num_points = 4; /* Fill in number of points in list */ 
Fill_list [0] .points = f illjpointsl; /* Pointer to point array */ 
pfill_area3(&Fill_list[0]) ; /* Create a fill area element */ 

pset_int_colr_ind(3) ; /* Assign default index color 3 to face */ 
Fill_list [1] .num_points = 4; 
Fill_list [1] .points = f ill_points2; 
pf ill_area3 (&Fill_list [1] ) ; 

pset_int_colr_ind(2) ; /* Assign default index color 2 to face */ 
Fill_list [2] .num_points = 4; 
Fill_list [2] .points = f ill_points3; 
pf ill_area3 (&Fill_list [2] ) ; 
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} 



pset_int_colr_ind(4) ; /* Assign default index color 4 to face */ 
Fill_list [3] .num_points = 4; 
Fill_list [3] .points = f ill_points4; 
pf ill_area3 (&Fill_list [3] ) ; 

pset_int_colr_ind(5) ; /* Assign default index color 5 to face */ 
Fill_list [4] .numjpoints = 4; 
Fill_list [4] .points = f ill_j?oints5; 
pf ill_area3 (&Fill_list [4] ) ; 

pset_int_colr_ind(6) ; /* Assign default index color 6 to face */ 
Fill_list [5] .numjpoints = 4; 
Fill_list [5] .points = f ill_points6; 
pf ill_area3 (&Fill_list [5] ) ; 

pclose_struct () ; /* Close filled drawing structure */ 

make_identity (identity) ; 

popen_struct (DISPLAY_STRUCT) ; /* Open the top level display structure */ 

pset_view_ind(VIEW) ; /* Set the view index to be used */ 

pset_hlhsr_id(PHIGS_HLHSR_ID_ON) ; /* Turn on Z buffering */ 

padd_names_set (&nset_names) ;/* Add nameset for picking (PICKABLE) */ 

plabel (TRANS) ; /* Insert a label for future updates */ 
pset_local_tran3 (identity, PTYPE_RE PLACE) ; 

/* set transformation matrix*/ 

pexec_struct (FILLBOX) ; /* Include the filled square */ 

pexec_struct (POLYBOX) ; /* Include the line drawn square */ 

pset_hlhsr_id(PHIGS_HLHSR_ID_OFF) ; /* Turn off Z buffering */ 

pclose_struct () ; 

ppost_struct(WS, DISPLAY_STRUCT, 1.0); /* Post DISPLAY_STRUCT, prio 1 */ 

pupd_ws (WS, PUPD_PERFORM) ; /* Update the workstation */ 

pset_edit_mode(PEDIT_REPLACE) ; /* Set edit mode to replace */ 



/* 

make_ident ity 

This routine sets the passed matrix to be an identity matrix. 
*/ 



( 



( 
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make_identity (matrix) 

Pmatrix3 matrix; 
{ 



matrix [0] [0] 


= 


1, 




matrix[0] [1] 


= 


0, 




matrix[0] [2] 


= 


0, 




matrix [0] [3] 


= 


0, 




matrix[l] [0] 


= 


0, 




matrix [1] [1] 


= 


1 




matrix [1] [2] 


= 







matrix [1] [3] 


= 







matrix[2] [0] 


= 







matrix[2] [1] 


= 







matrix[2] [2] 


= 


1 




matrix[2] [3] 


= 







matrix [3] [0] 


= 







matrix[3] [1] 


= 







matrix [3] [2] 


= 







matrix [3] [3] 
} 


= 


1 




Cleanup () 
{ 
punpost all stri 






acts(WS) 


pdel_all structs ( 


; 


pclose ws (WS) ; 






pclose_phigs () ; 









/* Cleanup routine when done 

/* Unpost all structures on ws 

/* Delete all structures */ 

/* Close workstation */ 

/* Close PHIGS */ 
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header4,,h 



/•* 



header 4 .h 
This file contains header information for example 4 programs. 

Author: James Buckmiller May 1990. 

Modified: J. Buckmiller Mar 1991. Approved C binding 

Copyright (C) 1990, Evans & Sutherland 



*/ 



C 



#define WS 
#define POLYBOX 
# define FILLBOX 



#define DISPLAY__STRUCT 3 
#define VIEW 4 

tdefine TRANS 5 

#define SPACEKEYSYM 32 
#define MAXDIALS 8 
#define CHARS_PER_DIAL 8 

#define SAFEJPEX( routine) Error_Check ( FILE , 

♦define DEG TO RAD(D) ((3.14159265358 / 180.0) 



/* number of dials on dials box */ 
/* size of dials labels */ 

LINE f routine) 

(D)) 



fdefine DIALSCALE .005 
#define PICKABLE 10 



/* Dial scale value */ 

/* name for inclusion filter */ 



( 



extern Window myWin; 
extern Display *dpy; 
extern char *ProgramName; 



extern int Major__op; 
extern int First_ev; 
extern int First err; 



/* input extension values */ 



extern Pint_list nset_names; /* Pick list nameset declaration */ 

extern XPickFilter pick__incl r pick_excl; /* Pick filters declaration 

extern Pint namesints [1] ; /* Name arrays for nameset */ 

extern PC pc;/* pick context */ 

extern Pint PEX_error; /* For PEX error numbers */ 
extern Pmatrix3 identity; 



C 
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Additional Information 
General Computer Graphics 

Foley, James D., Andries van Dam, Stephen K. Feiner, and 

John F. Hughes, Computer Graphics - Principles and Practice, Second 
Edition, Reading, MA: Addison- Wesley Publishing Company, 1990. 

Newman, William M. and Robert F. Sproull, Principles of Interactive Com- 
puter Graphics, Second Edition, New York: McGraw-Hill Book Compa- 
ny, 1979. 

Computer Graphics Standards 

Information processing systems - Computer graphics - Programmer's 
Hierarchical Interactive Graphics System (PHIGS), Part 1 -functional 
description, International Standard, ISO/IEC 9592-1: 1988(E). 

Information processing systems - Computer graphics - Programmer's 
Hierarchical Interactive Graphics System (PHIGS), Part 2 - archive file 
format, International Standard, ISO/IEC 9592-2: 1988(E). 

Information processing systems - Computer graphics - Programmer's 
Hierarchical Interactive Graphics System (PHIGS), Part 3 - clear-text 
encoding of archive file, International Standard, ISO/IEC 9592-3: 1988(E). 

Information processing systems - Computer graphics - Programmer's 
Hierarchical Interactive Graphics System (PHIGS), Part 4 - Plus 
Luminire und Surfaces (PHIGS PLUS), DIS PHIGS PLUS, 
14 February 1991, ISO/IEC 9592-4: 199x. 

Standards in the Computer Graphics Industry, Fairfax, VA: National Com- 
puter Graphics Association, 1989. 
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2, X Extensions 



Introduction 



This chapter describes the following ESV Workstation extensions to the X 
server: 

• X Input Extension 

• X Picking Extension 

• E&S Extension 

• X Overlay Functionality 

• X Multiscreen Functionality 

• X Video Timing Formats Functionality 

• X Miscellaneous Traversal Functionality 
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X Input Extension 

The X Consortium developed the X Input Extension for what are called "ex- 
tended devices." This section describes the X Input Extension functions and 
their implementation in the ES V Workstation. It does not contain a complete 
description of the X Input Extension. Additional information can be found in 
the on-line man pages. This section discusses the following topics: 

• "Implementation Notes" provides the basic information necessary for 
using the X Input Extension on an ES V Workstation. 

• "Function Descriptions" describes some of the key X Input Extension 
functions. 

• "Macro Descriptions" describes some of the X Input Extension 
macros. 

• "Event Records" describes some of the X Input Extension event 
records that can be received in an XNext Event call. 

• "Additional Structures" describes some of the structures used by the 
X Input Extension. 

Implementation Notes 

Extended Device Event Handling 

There are six classes of extended devices: KEY, BUTTON, VALUATOR, 
PROXIMITY, FOCUS, and FEEDBACK. A physical device may provide more 
than one class of information; e.g., a knob box may provide both VALUATOR 
and FEEDBACK. 

Event Selection 

Input event selection for extended devices requires a little more work than 
standard X events. There are four steps to selecting events for a set of devices. 

1. Get the List of Available Devices 

First, the application does an inquiry to determine the list of available devices. 
This is done with XListlnputDe vices. This returns a list of XDevicelnfo 
structures which contains information about the devices supported by an im- 
plementation of the X Input Extension. This information includes the ID, 
type, name, number of classes supported, and a list of class information. The 
list of input devices always includes the X pointer and X keyboard. 

Following is a list of extension devices supported in the ES V Workstation 
implementation and their associated classes. 



C 



( 



c 
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Name Class 

XLBUTTONBOX BUTTON, FEEDBACK 

XLKNOB_BOX VALUATOR, FEEDBACK 

XIJTABLET VALUATOR, BUTTON 

XI_SPACEBALL VALUATOR, BUTTON 

2. Open the Devices 

Each device is opened for use by an application calling XOpenDevice with 
the device ID returned in the XDevlcelnf© list. This procedure returns a list 
of XDevice structures containing specific class information. 

The following example shows how to get a list of extended devices and 
open them. 

Display *display; 

Window window; 

XDevicelnfo *devicelist, *dl; 

XDevice *dials = NULL; 

XDevice *t ablet = NULL; 

XDevice *space = NULL: 

XDevice *button = NULL; 

XID dials_id, tablet_id, space_id, button_id; 

int ndev, i; 



devicelist = XListlnputDevices (display, ndev) 
dl = devicelist; 

for (i = 0; i < ndev; i++, dl++) 
{ 
if ( ! strcmp (XI_KNOBBOX, dl->name) ) 
{ 
dials_id = dl->id; 

dials = XOpenDevice (display, dials_id) ; 
} 

if ( ! strcmp (XIJTABLET, dl->name) ) 
{ 
tablet_id = dl->id; 

tablet = XOpenDevice (display, tablet_id) ; 
} 

if (! strcmp (XI_SPACEBALL, devices ->name) ) 
{ 
space_id = dl->id; 

space = XOpenDevice (display, space_id) ; 
} 

if ( ! strcmp (XI_BUTTONBOX, dl->name) ) 
button_id = dl->id; 

button = XOpenDevice (display, button_id) ; 
} 
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3. Find Event Types and Classes | 

X extension events are returned through a call to XNextEvent just like normal 
X events. However the event type is determined by the extension based on an 
internal event type that is offset by a server determined base. This means that 
the application must determine the event types in order to compare them to 
values returned by the call to XNextEvent. Also, in order to select events, the 
event class of the event must be determined. 

The information that has been returned at this point can be supplied to 
macros to find the event types and event classes for each device. Some 
examples of these are DevlceButtonPress, DeviceButtonRelease, and 
DeviceMotionNotify. The macros available are listed on the XOpenDevice 

man page. 

4. Select Extension Events 

The event class information is used by XSelectExtension Event to select 
events from extension devices. The following example shows how to get the 
event classes and use them to select events. 



XEventClass *eventClass [2] ; 
EventType *event__type [ 2 ] ; 
int event_count = 
int DeviceMotion = -1; 
int PevicePress = -1; 



if (button) 
{ 
DeviceButtonPress (button, DevicePress, 

eventClass [event_count] ) ; 
e vent_count ++ ; 
} 

if (dials) 
{ 
DeviceMotionNotify (dials, DeviceMotion, 

eventClass [event__count]) ; 
event_count++; 
} 

XSelectExtensionEvent (display, window, eventClass, 
event count) ; 



( 
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Event Handling 

Below is a table that lists each device, and the associated structure definition 
of events that are generated. The event type is not predefined as in standard 
X events. The values for the event types are generated from the above macros. 
The structures for each event type are described in "Event Records." 

Device Structure 

BUTTONBOX XDeviceButton Event 

KNOB_BOX XDeviceMotionEvent 

TABLET XDeviceMotionEvent, XDeviceButtonEvent 

SPACEBALL XDeviceMotionEvent, XDeviceButtonEvent 

The following example shows how to process input extension events. 

XEvent pe ; 

XDeviceMotionEvent *dm = (XDeviceMotionEvent *) & pe; 

XDeviceButtonEvent *db = (XDeviceButtonEvent *) & pe; 



XNext Event (dpy, &pe) ; 
switch (pe.type) 
{ 
/* process normal X events with case xxx: */ 



/* process extension events */ 
default: 

if (pe.type == DeviceMotion) 

{ 
if (dm->deviceid == tablet id) 



/* Process tablet motion */ 
else if (dm->deviceid == space_id) 

/* Process space ball motion */ 
else if (dm->deviceid == dials_id) 

/* Process knob box motion */ 



} 

else if (pe.type == DevicePress) 

{ 

if (db->deviceid == tablet_id) 

{ 
/* Process tablet button press */ 
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lse if (db->deviceid == space_id) 
/* Process space ball button press */ 
else if (db->deviceid == button_id) 
/* Process button box button press */ 



( 



} 

break; 
} 

Feedback Control 



Feedback is used for sending to an extension device. The two devices on the 
ESV Workstation that support it are the knob box and button box. The knob 
box has an 8 character display for each knob and the button box has an LED 
for each button. These devices are sent to using the 
XChangeFeedbackControl function. 

The following example shows how this is done for the first knob label. 

Display ^display; 

XDevice *dials; 

XStringFeedbackControl feeder; _ 

Key Sym message [8] ; m 

char * label; V,. 



/* the characters to display must be encoded into KeySyms */ 

feeder. class = StringFeedbackClass; 
feeder .length = sizeof (XStringFeedbackControl) + 
(strlen (label) * sizeof (KeySym) ) ; 
feeder.num_keysyms = strlen (label) ; 
feeder .syms_to_di splay = message; 
feeder. id = 0; /* knob 0*/ 
XChangeFeedbackControl (display, dials, DvString, &feeder) ; 



C 
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Function Descriptions 

XListlnputDevices 

Syntax 

XDevicelnfo * 

XListlnputDevices {display, ndevices) 

Display *dispiay 9 

int *ndevices; 

Arguments 

display The connection to the X server. 

ndevices The address of a variable into which the number of 

available input devices can be returned. 

Description 

The XListlnputDevices procedure is used to determine the number and types 
of extension devices available for input. An array of XDevicelnfo structures 
is returned, with one element in the array for each device. The number of 
elements is returned in the ndevices argument. 

XFreeDeviceList 

Syntax 

XFreeDeviceList (iistj 
XDevicelnfo *iist, 

Argument 

iist The pointer to the XDevicelnfo array returned by 

a previous call to XListlnputDevices. 

Description 

The XFreeDeviceList procedure frees the list of input device information. 
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XOpen Device 

Syntax 

XDevice * 

XOpenDevlce (display, device id) 
* display; 



c 



Display 
XID 

Arguments 

display 

device Id 



Description 



devlcejd; 



The connection to the X server. 



The ID that identifies the device to be opened. This 
ID is obtained from the XListlnputDevices re- 
quest. 



This procedure opens the device for the application and returns an XDevice 
structure if successful. The XDevice structure contains a pointer to an array 
of Xlnpuf Classlnfo structures. Each element in that array contains informa- 
tion about events of a particular input class supported by the input device. A 
program can determine the event type and event class for a given event by us- 
ing macros defined by the input extension. 

XCIoseDevice 



Syntax 




int 

XCIoseDevice (display, device) 

Display "display; 

XDevice *devlce a , 


Arguments 




display 


The connection to the X server. 


device 


The device to be closed. 



( 



Description 

This function closes the device and frees the XDevice structure. 



C 
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XSelect Extension Event 
Syntax 

XSelectExtensionEvent (display, w, eventjist, event_counf) 



Display 
Window 
XEventClass 
int 

Arguments 

display 

w 

eventjist 

event_count 
Description 



"display; 
w, 

*eventjist, 
event_count, 



The connection to the X server. 

The window whose events you are interested in. 

A pointer to a list of XEventClasses that specify 
which events are desired. 

The number of elements in the event list . 



This procedure requests that events matching the events and devices de- 
scribed by the event list are reported to the application. The elements of the 
XEventClass array are the event_class values returned by the Input Exten- 
sion macros to retrieve the event classes. 
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XSefect Extension Event 

Syntax 

XChangeFeedbackControl(d/$p/ay, device, mask, control) 
Display '"display; 

XDevice "device; 

Mask mask; 

XFeedbackControl *control; 

Arguments 

display The connection to the X server. 

device The device to be used for feedback. 

mask The mask specific to each feedback that describes 

how the feedback is to be modified. 

control The address of an XFeedbackControl structure 

that contains the new values for the feedback. 

Description 

This function is provided to manipulate those input devices that support feed- 
back. A BadMatch error will be generated if the requested device does not 
support feedback. You can determine whether or not a given device supports 
feedback by examining the information returned by the XOpenDevice re- 
quest. For those devices that support feedback, XOpenDevice will return an 
XlnputCiasslnfo structure with the input class field equal to the constant 
FeedbackClass (defined in the file Xl.h). The feedback classes that are cur- 
rently defined are: KbdFeedbackClass, PtrFeedbackClass, 
StringFeedbackClass, IntegerFeedbackCKass, LedFeedbackClass, and 
BellFeedbackOlass. 

An input device may support zero or more feedback classes, and may 
support multiple feedbacks of the same class. Each feedback contains a class 
identifier and an ID that is unique within that class for that input device. The 
ID is used to identify the feedback when making an 
XChangeFeedbackControl request. 

The XChangeFeedbackOontrol function modifies the values of one 
feedback on the specified device. The feedback is identified by the ID field of 
the XFeedbackControl structure that is passed with the request. The fields of 
the feedback that are to be modified are identified by the bits of the mask that 
is passed with the request. XChangeFeedbackControl can generate a 
BadDevice, BadMatch, or BadValue error. 



c 



c 



c 



2-10 ESV Workstation Reference Manual [2.0] 



X Extensions 



Macro Descriptions 

You can determine the event type and event class for a given event by using 
the macros defined below. The event type is used to check the type field of 
an event generated by XNextEvent. 

The name of the macro corresponds to the desired event, and the macro is 
passed to the structure that describes the device from which input is desired. 

• DeviceButtonPress(cf, type, class) 

Returns the event type and class of button press events for the 
BUTTON device class. The parameter d is a pointer to an XDevice 
structure for a BUTTON class device. 

• DeviceButtonRelease(tf, type, class) 

Returns the event type and class of button release events for the 
BUTTON device class. The parameter d is a pointer to an XDevice 
structure for a BUTTON class device. 

• DeviceMotionNotify(d, type, class) 

Returns the event type and class of motion events for the VALUATOR 
device class.The parameter d is a pointer to an XDevice structure for 
a VALUATOR class device. 
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Event Records 



Device Button Events 

DeviceButtonPressed/DeviceButtonReleased events are generated when 
a key is pressed or released on a BUTTON extension device and that type of 
event is selected. The structure associated with the DeviceBuffonPressed/ 
DeviceButtonReleased event is defined as follows: 



c 



typedef struct { 




int 


type; 


unsigned long 


serial; 


Bool 


sendjevent, 


Display 


"display] 


Window 


window, 


XID 


devlceld; 


Window 


root, 


Window 


suhwindow, 


Time 


time; 


int 


x,V, 


int 


x_root, yjroot, 


unsigned int 


state; 


unsigned int 


button; 


Bool 


same_screen; 


unsigned Int 


device state; 


unsigned char 


axes_count, 


unsigned char 


first_axis; 


int 


axls_data[6]; 


} XDeviceButtonEvent; 


typedef XDeviceButtonEvent XDeviceButtonPressedEvent; 


typedef XDeviceButtonEvent XDeviceButtonReleasedEvent; 



( 



c 
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Device Motion Events 

The DeviceMotion event is generated when there is motion on a VALUATOR 
extension device. The structure associated with the DeviceMotion event is 
defined as follows: 



typedef struct { 




int 


type; 


unsigned long 


serial; 


Bool 


sendjevent, 


Display 


'display, 


Window 


window, 


XID 


devlceld; 


Window 


root, 


Window 


subwindow; 


Time 


time; 


int 


x,y; 


int 


x_root, y_root, 


unsigned int 


state; 


char 


ls_hlnt; 


Bool 


same_screen; 


unsigned int 


devlce_state; 


unsigned char 


axes_count, 


unsigned char 


flrst_axis; 


int 


axls_data[6]; 



} XDeviceMotionEvent; 



ESV Workstation Reference Manual [2.0] 



2-13 



X Extensions 



Additional Structures £ 

These are some of the input structures referenced by the X input Extension. 
typedef struct JCAnyCiasslnfo *XAnyClassPtr; 

typedef struct JCAnyCiasslnfo { 

XID class; 

int length; 

} XAnyClasslnfo; 

typedef struct JCDevicelnfo *XDevicelnfoPtr; 

typedef struct _XDevicelnf o { 

XID /<*; 

Atom type; 

char *name; 

int ncnv classes; 

int use-, 

XAnyCiassPtr Inputciassinfo; 
} XDevicelnfo; 

typedef struct JCButtonlnfo *XButtonlnfoPtr; 

typedef struct JCButtonlnfo { 

XID class; 

int length; 

short num_buttons; 

} XButtoninfo; 

typedef struct JCAxislnfo *XAxislnf©Ptr; 

typedef struct JCAxislnfo { 

int resolution; 

int min_valu@; 

int max_yalue; 

}XAxislnfo; 

typedef struct _.X Valuator Into *XValuatorlnfoPtr; 



c 



c 
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typedef struct _XValuatorlnfo { 



XID 
Int 

unsigned char 
unsigned char 
unsigned long 
XAxIslnfoPtr 
} XValuatorlnfo; 



class; 

length; 

num axes; 

mod®; 

motion__huffer, 

axes; 



typedef struct { 
unsigned char 
unsigned char 

} XInputGlasslnfo; 



Input class: 
event_Jype_base; 



typedef struct { 

XID 

int 

XInputGlasslnfo 
} XDevice; 



devicejd; 

num_eiasses; 
*classes; 
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X Picking Extension 



PHIGS does not interact well with the X Window System. The PHIGS input 
model is not compatible with the X input model. If you use an output-only 
PEX workstation and find the workstation's window ID, you can use X input 
functions with PHIGS output functions. This allows your application to re- 
ceive input events, but leaves you with no way to do picking on the displayed 
PEX data structure. The picking extension described in this chapter is a solu- 
tion to this problem. 

This picking extension allows picking operations on PEX graphics 
displayed in an X window to report their results as events back to your 
application. 

The data returned by the picking extension is more detailed than that de- 
fined by PEX. The pick data returned by the picking extension can include the 
following: 

• A window space coordinate on the picked primitive, which is within 
the pick box 

• A model space coordinate on the picked primitive, which is within the 
pick box 

• An index for identifying which element of the picked primitive was 
picked (e.g., the line item of a polyline primitive or the character with- 
in a text string) 

• The parameterized values which identify a point on a NURB curve or 
NURB surface 



Graphics applications often encounter the need for the user to identify some 
graphics element from its position on the display device. The X Picking Ex- 
tension addresses the need for identifying PEX graphics elements in PHIGS 
workstation windows. 

A graphics application initiates a pick operation by specifying the win- 
dow of a PHIGS workstation, a picking context (PC), and the location about 
which the pick box is to be centered. The graphics subsystem is then respon- 
sible for determining the picked graphics primitive. It does this by traversing 
all posted structures to the PHIGS workstation and determining which of them 
fall (at least some portion) within the pick box, and whether they are pickable 
according to the inclusion and exclusion filters of the PC. From this set of 
graphics primitives, one is returned to the graphics application according to 
the mode of the PC. 

Information about that graphics primitive is returned to the application in 
an X extension event form. The information that can be returned includes the 



2-16 ESV Workstation Reference Manual [2.0] 



Overview 



c 



c 



X Extensions 



screen and model coordinates of the primitive, the element number and struc- 
ture ID of the primitive, the current pick ID at the moment the primitive was 
traversed, and the complete path (element, struct, pickid) to the top of the 
posted structure. 

The X event mechanism is used to prevent delaying of the application 
while the graphics subsystem is traversing the posted structures. 

A prepick operation is also available through the X Picking Extension. It 
can be used to highlight the set of graphics primitives which may be returned 
as the result of a pick operation. No events are generated as the result of a 
prepick operation. 

A PC is used in the server to maintain state information that affects pick 
operations. This is analogous to a graphics context (GC) used in X drawing 
operations. The PC retains the settings of the following: 

• pick mode - determines selection criteria 

• pick box size - width and height of pick box 

• pick highlighting color - pixel value for highlighting 

• pick highlighting mode - amount of primitive to highlight 

• pick inclusion filter - set of allowed names when picking 

• pick exclusion filter - set of disallowed names when picking 

• pick return values - hints to avoid wasted computation 

In a similar manner to the use of a GC, a PC must be created before it can 
be used. Values of the PC may then be set to any of the legal values specified 
by this document. An identifier for the PC is always specified for pick or 
prepick operations. A PC should be destroyed by calling XFreePC when it is 
no longer needed. An application may create as many PCs as it requires. More 
than one pick or prepick operation may be concurrently pending on the same 
PC. 

X Picking Data Structures 

The picking extension routines use the following data structures and types: 

• PC (Pick Context) 

• XPickEvent 

• XPickFilter 

• XPickPath 

• XPickPathEvent 

• XPickPathltem 
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PC (Pick Context) f 

Syntax ^ 

typedef KID PC; 

Description 

The state of a pick operation is associated with a unique pick context identi- 
fier. All state information needed by the server is associated with a pick con- 
text. More than one pick request can be pending a pick context at any one 
time. 



c 
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XPickEvent 

Syntax 

typedef struct { 

int type; 

unsigned long serial; 

Bool send__event; 

Display 'display, 

PC pc; 

Window window; 

Time time; 

int prim_type; 

int vaiid_fiags; 

int itemid; 

int elementid; 

int structureid; 

int pickid; 

float modeix-, 

float modely; 

float modeir, 

float screenx: 

float screeny\ 

float screenr, 

float prim_spci1; 

float prim_spcl2; 
} XPickEvent; 
Arguments 

fype Equal to the value returned in the second argument of 

XGetPickEventType. 

ser/a/ The serial number of the event. 

send_event True if this event was generated by a XSend Event call. 

display The display that generated the event. 

pc The ID of the pick context which generated this event. 

Multiple picks can be active at one time. Sending the pc 
back lets you know which pick completed. 

window The window in which the event was generated. 
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time The time stamp of the event (when it happened). m 

prim_type The type of the picked PEX primitive. It is set to 

plcknopick if nothing was picked. Otherwise, it is set to 
one of 

pick_marker 

pick_marker2d 

pick text 

pick_text2d 

pick_annotationtext 

pick annotationtext2d 

pick_polyline 

pick_polyline2d 

pick_polylinesetdata 

pick fiiiarea 

pick fiilarea2d 

pickjillareaset 

pick_fillareas@t2d 

pickjillareadata 

pick fillareasetdata 

pickjrianglestrfp 

pick quadrilateralmesh / 

pick__setfillareasetdata V 

pick_cylinder 

pick sphere 
vaiJd_fiags Indicates which of the following fields in the XPickEvent 
structure are valid. These flags may consist of any mixture 
of 

pickscreenpt valid 

pickmodelpt valid 

pick_primspcl1_valid 

pick _primspcl2 valid 

If it is possible to determine the screen coordinates of the 
point on the picked primitive which is within the pick box, 
pick_screenpt_valld will be set. 

If it is possible to determine the model coordinates of the 

point on the picked primitive which is within the pick box, 

pick_modelpt_valid will be set. If the current 

transformation matrix is not invertible or if the model point 

calculation has been turned off in the pick context by the 

client, pick_mode!pt_vaEid will not be set and the values in 

modelx, modely, and modelz will not be usable. f~ 
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If valid data exists in prim_spcl1 for the picked primitive, 
pick_primspcl1_valid will be set. If valid data exists in 
prim_spcl2 for the picked primitive, 
pick_primspcl2_valid will be set. 



itemld 



The item number of the picked structure. The interpretation 
of the item number depends upon the primitive type. The 
table below describes how to interpret the value for the 
various types of primitives. The primitive's index tells 
which primitive in the PHIGS element was picked. 

Primitive Type Description 



pickmarker 

pick marker2d 

pick_text 

pick_text2d 

pick annotationtext 

pick_annotationtext2d 

pick_polyline 

pick_polyline2d 

pick_polylineset 

pickfillarea 

pick_fillarea2d 

pickfillareaset 

pick_fillareaset2d 

pickfillareadata 

pick fjllareasetdata 

picktrianglestrip 



index of the picked marker 
index starts with 

index of the picked marker 
index starts with 

index of the picked character 
index starts with 

index of the picked character 
index starts with 

index of the picked character 
index starts with 

index of the picked character 
index starts with 

index of the picked line segment 
index starts with 1 

index of the picked line segment 
index starts with 1 

index of the picked line segment 
index starts with 1 

always set to zero 

always set to zero 

always set to zero 

always set to zero 

always set to zero 

always set to zero 

index of the picked triangle 
index starts with 
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pick_quadrilateralmesh 

pick setf illareasetdata 
pick cySinder 

pick_sphere 



index of the picked mesh 
index starts with 

always set to zero 

index of the picked cylinder 
index starts with 1 

index of the picked sphere 
index starts with 



C 



elementid The element ID of the picked structure. 

structureid The structure ID of the picked structure. 

piakkl The pick ID associated with the structure. 

modelx The 3D coordinates of the pick point in model 

modeiy space. If the picked primitive is 2-dimensional, the z- 

modelz value will be set to zero. 

screenx The pixel screen coordinates of the pick point 

screeny relative to the window in which the pick was performed. 

screenz The value of screenz is implementation dependent. 

Notes The terms screenx and screeny are 

misnomers because their values are relative to 
the window and not to absolute screen 
coordinates. 

prim__spc!1 Reserved for future enhancements. Until then, 

pickjjrimspcI1_valid will never be set in validjlags. 

prim_spc!2 Reserved for future enhancements. Until then, 

pickjjrimspcl2_walid will never be set in valid_f lags. 

Description 

An XPickEvent is returned for each XPiekQ call made by a client application. 
If no graphics primitives were in the pick box, or if no graphics primitives 
within the pick box were pickable, the value of prlmjtype will be set to 
pick_nopick. Otherwise, one item will be returned as the result of the pick 
operation and the elements of the XPickEvent structure will be set as 
indicated. 

Note that the client application must have selected to receive 
XPickEvents from the window in which the pick operation is to occur. 



( 



( 
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XPickFilter 

Syntax 

typedef struct { 

int number, 

int *Integers- 9 

} XPickFilter; 
Description 

Pick filters are used to specify which elements will be included or excluded 
during a pick operation. The XPickFiiter structure is the same as a PHIGS 
Pintlst. Only the names have been changed. 
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XPickPath 




Syntax 




typedef struct { 




Display 


A display; 


Window 


window, 


PC 


pc, 


Window 


suhwindow, 


int 


prim_type; 


int 


length; 


int 


itemidl; 


XPickPathitem 


"path; 


} XPickPath; 




Arguments 





c 



pc 



prim_type 
length 

itemid 



path 



The ID of the pick context which generated the 
XPickPath Events used to construct this pick path. Multiple 
picks can be active at one time. Sending the pc back lets you 
know which pick completed. 

The same as in the XPickEvent description. 

The number of XPickPathitem records in the pick path. If 
nothing was picked, the length will be zero. 

The item number within an element of a structure that was 
actually picked. This is the same as in the XPickEvent 
description. This is only meaningful for the last element in a 
path so it is returned separately from the rest of the path. 

A pointer to a vector of XPickPathitem records. The last 
item in the vector is the picked primitive. 



Description 



An XPickPath structure is returned by the XPickPathEventToPath routine 
when it has assembled a complete pick path from a group of XPickEvent 
records. 



C 



c 
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XPickPathEvent 



Syntax 

typedef struct { 

int 

unsigned long 

Bool 

Display 

PC 

Window 

Time 

int 

int 

Int 

int 

XPickPathltem 
} XPickPathEvent; 
Arguments 



type; 

serial; 

send_event, 

^display; 

per, 

window, 

time; 

primjtype; 

itemid; 

pathjength; 

first_path; 

pattm; 



type 

serial 

send_event 
display 
pc 

window 
time 

prim_type 
itemid 



pathjength 



The type of the event. It is equal to the value returned in the 
third argument to XGetPickEventType. 

The serial number of the event. 

True if the event was generated by an XSendEvent call. 

The display that generated the event. 

The ID of the pick context which generated this event. 
Multiple picks can be active at one time. Sending the pc 
back lets you know which pick completed. 

The window in which the event was generated. 

The time stamp of the event (when it happened). 

The same as in the XPickEvent description. 

The item number within an element of a structure that was 
actually picked. This is the same as in the XPickEvent 
description. This is only meaningful for the last element in a 
path so it is returned separately from the rest of the path. 

The total length of the path.; one greater than the highest 
path item index. A path length of indicates that nothing 
was picked. 
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first_path 

path 
Description 



The position in the pick path of the first item in the path. For 
example, if path length is 6 and first_path is 4 then this 
event contains the 5th and 6th items in the path. Paths items 
are numbered starting at 0. 

A vector of up to four path items. It contains a portion of the 
actual path data. 



C 



The complete pick path is reported to the client as one or more 
XPickPathEvenfs. If the path length to the picked primitive is more than 
four, multiple XPIckPath Events are sent to the client as needed to return the 
complete path. 



C 



c 
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XPickPathltem 
Syntax 

typedef struct { 

Int 

int 

int 

} XPickPathltem; 

Arguments 
elementid 

structured 
pickid 



elementid; 

structured; 

pickid; 



The element number of the item within the PHIGS structure. 

The ID of the PHIGS structure. 

An ID associated with the picked structure. It is the current 
pick ID for the element in the XPickPathltem. 

Description 

An XPickPathltem structure identifies a structure in the pick path. 
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Interface Routines 



All interface routines return an integer value to indicate success or failure of 
the call. They return a success if the call worked or an error code indicating 
the type of failure. 

The interface routines include the following: 

XCreatePC 

XFreePC 

XFreePickFilter 

XFreePickPath 

XGetPickBoxSize 

XGetPickEventType 

XGetPickFilters 

XGetPickHlghlightingColor 

XGetPickHighlightingMode 

XGetPlckMode 

XGetPickReturnVals 

XGetSelectedPickEvents 

XPick 

XPickPathEventToPath 

XPrePick 

XSelectPickEvents 

XSetPickBoxSize 

XSetPickFilters 

XSetPickHighlightingColor 

XSetPickHighlightingMode 

XSetPickMode 

XSetPickReturnVals 



( 



c 
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Syntax 




int 




XCreatePC(cfpy, type, pc)\ 


Display 


*dpy; 


int 


type; 


PC 


*pc; 


Arguments 




<*py 


The display on w 


type 


The type of grapl 



perform pick. One of the following defined constants. 

pick_PEX 

Currently only PHIGS structures can be picked. We expect 
that other graphics interfaces will also need a way to report 
picking information in an X compatible way. 

pc Where you want the new pick context identifier stored. 

Description 

An XCreatePC call returns a new PC that you can use in an XPick or 
XPrePick call. The new PC has the following default values which can be 
changed and retrieved: 

pick mode = pickjirst 

return values = pick_compute_modelpt | pick_compute_special 

pick box size = 9x9 pixels 

highlighting color = white 

highlighting mode = pick_highiighting_off 

inclusion filter = none 

exclusion filter = none 
Errors 
BadAlloc 
BadValue (returned if type is not pick_PEX) 



ESV Workstation Reference Manual [2.0] 



2-29 



X Extensions 



XFreePC f 

Syntax 
Int 
XFreePC(dpy 9 pc)\ 

Display *dpy 9 

PC *pc; 

Arguments 

dpy The display on which the PC was created. 

pc The PC to be freed. 

Description 

An XFreePC call removes a PC from the server and frees all related 
resources. 

Errors 

BadPC 



( 



c 
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XFreePickFilter 

Syntax 

int 

XFreePlckFilter(f//fe/) 

XPtekFllter 'filter, 

Argument 

filter A pointer to an XPickFilter structure. 

Description 

An XFreePickFilter call releases the storage used by a pick filter. It is a safe 
way to free the storage. 
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XFreePickPath f 

Syntax 

int 

XFreePickPath(paf/7) 

XPickPath *path; 

Argument 

path A pointer to an XPickPath structure. 

Description 

An XFreePickPath call releases the storage used by a pick path. It is a safe 



way to free the storage. 



c 
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XGetPickBoxSize 
Syntax 
int 

XGetPickBoxSize(c/py, pc, width, height) 
Display *dpy, 



PC 
int 
Int 
Arguments 
dpy 
pc 

width 
height 
Description 

An XGetPickBoxSize call gets the pick box size from a PC. See 
XSetPickBoxSize for more information. 

Errors 

BadPC 



pc, 

*width; 

'height, 

The display on which the PC was created. 
A pick context whose value you are querying. 
Where to put the width of the pick box. 
Where to store the height of the pick box. 
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XGetPickEvenfType 




Syntax 




int 

XGetPickEventType(dpy, PickEventType, PickPathEventType) 

Display *dpy, 

int *PickEventType; 

int * PickPathEventType; 


Arguments 




dpy 


The display on which you are going to perform a 
pick. 


PickEventType 


Where you want the type of a PickEvent to be 
stored. 


PickPathEventType 


Where you want the type of a PickPathEvent to be 
stored. 


Description 





An XGetPickEventType call returns the type of an XPickEvent and an 
XPickPath Event. This information is needed so that the programmer can 
identify these events when they are returned from XNextEvent. 



C 
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XGetPickFilters 
Syntax 
int 



XGetPickFilters(cfpy, pc 9 Inclusion, exclusion) 
Display *dpy, 

PC pc: 

XPickFilter "inclusion; 

XPickFilter "exclusion; 

Arguments 

dpy The display on which the PC was created. 

pc A pick context whose value you are querying. 

Inclusion A pointer to a pointer to an XPickFilter structure. It will be 

set to point to the current value of the inclusion filter. 

exclusion A pointer to a pointer to an XPickFilter structure. It will be 

set to point to the current value of the exclusion filter. 

Description 

An XGetPickFilters call returns the picking filters of a picking context. 
XFreePickFilter should be called to release the storage used for each of the 
inclusion and exclusion filters 

Errors 

BadPC 
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XGetPickHighlightingColor f 

Syntax 
int 

XGetPickHighlightingColor(dpy, pc, color) 
Display *dpy, 

PC pc; 

unsigned long "color, 
Arguments 

dpy The display on which the PC was created. 

pc A pick context whose value you are querying 

color Where to store the pixel value. 

Description 

An XGetPickHighlightingColor call gets the highlighting color from a PC. 
See XSetPickHighlightingColor for more information. 

Errors 

BadPC 



( 



( 
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XGetPickHighlightingMode 
Syntax 
int 

XGetPickHighlightingMode(cfpy, pc, mode) 
Display *dpy; 

PC pc\ 

int *mode; 

Arguments 

dpy The display on which the PC was created. 

pc A pick context whose value you are querying. 

mode Where to store the returned mode value. 

Description 

An XGetPickHighlightingMode call gets the current highlighting mode 
from a PC. See XSetPickHighlightingMode for more information. 

Errors 

BadPC 
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XGetPickMode f^ 

Syntax 
int 

XGetPiekMode(dpy, pc, mode) 
Display *dpy, 

PC pc, 

int "modei 

Arguments 

dpy The display on which the PC was created. 

pc A pick context whose value you are querying. 

mode Where to put the returned value. 



Description 

An XGetPickMode call gets the picking mode from a PC. See 
XSetPiakMode for more information. 

Errors 

BadPC 



( 
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XGetPickReturnVals 
Syntax 

XGetPickReturnVals(cfpy, pc, mask) 
Display *dpy, 

PC pc, 

unsigned long *maslq 
Arguments 

dpy The display on which you are going to perform a pick. 

pc A pick context whose value you are changing. 

mask A pointer to a long word in which to store the current values. 

Description 

An XGetPickReturnVals call gets the current value of the computation mask 
for the specified picking context. A computation mask serves as a hint to the 
server to avoid unnecessary additional computation when returning the 
details of a completed picking operation. See XSetPickReturnVals for more 
information. 

Errors 

BadPC 
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XGetSelectedPickEvents f 

Syntax 
int 

XGetSelectedPickEvents(dpy, win, mask) 
Display *dpy, 

Window win-, 

unsigned long *maslq 
Arguments > 

dpy *■ The display on which you have selected picking events. 

win A window from which you have selected picking events. 

mask Where to store the pick event mask. 

Description 

, An XGetSelectedPickEvents call gets the pick events mask from a window. 
The pick events mask determines which type of picjdng events will be sent to 
the window as the result of a pick operation. , •* t , 

Errors , 

BadWindow (returned if the window doesn't exist or isn't being used to dis- ^ 

play 3D graphics) f 



C 
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XPick 



Syntax 

int 

XPick(dpy, win, pc, x, y) 

Display *dpy, 

Window win; 

PC v pc, 

Int x; 

Int y, 

Arguments ., * ° 

dpy The display on which you are going to perform a pick. 

win The window in which you are going to pick. 

pc The ID of the pick context for the pick operation. All the 

parameters that control how a pick or prepick operation is 

done are taken from the pick context. 
x The x coordinate in pixels of the pick location relative to the 

window where the pick operation is to occur. 
y The y coordinate in pixels of the pick location relative to the 

window where the pick operation is to occur. 

Description 

An XPick call picks at the specified location in the specified window using 
the parameters associated with the specified pick context. 

XPick initiates a pick operation for the specified window according to the 
parameters set in the specified pc. A pick event and one or more pick path 
events will always be generated at the completion of the pick operation. They 
will be reported to the window on which the operation was performed if the 
setting of the pick events mask for that window has selected that event type. 

The pick operation causes a traversal of all posted structures on the PHIGS 
workstation associated with that window. Each of the drawn primitives is 
analyzed to determine if any portion of it falls within the pick box centered at 
the specified x and y. If two or more primitives fall within the bounds of the 
pick box, the mode of the pc determines which of the primitives to return as 
the result of the pick operation. (Refer to SetPickMode.) 

Errors 

Bad Alloc (returned if the server is out of memory) 
BadPC 

Bad Window (returned if the window doesn't exist or isn't being used to dis- 
play 3D graphics) 
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XPickPathEventToPath f 

Syntax ^ 

XPickPath 

*XPickPathEventToPath(evenf) 
XPickPafhEvent *event, 
Argument 

event A pointer to an XPickPathEvent 

Description 

XPickPathEventToPath is a utility function that can be used to merge a 
number of separate XPickPathEvent records into a single XPickPath 
structure. Because there is no real limit to the length of a pick path, one or 
more pick path events must be sent to transmit the entire path. 



C 
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XPrePick 

Syntax 
inf 
XPrePick(dpy, win, pc, x, y) 

Display *dpy, 

Window win; 

PC pc, 

int x; 

int y, 

Arguments 

dpy The display on which you are going to perform a pick. 

win The window in which you are going to pick. 

pc The ID of the pick context for the pick operation. All the 

parameters that control how a pick or prepick operation is 
done are taken from the pick context. 

x The x coordinate in pixels of the prepick location relative to 

the window where the pick operation is to occur. 

y The y coordinate in pixels of the prepick location relative to 

the window where the pick operation is to occur. 

Description 

An XPrePick call prepicks at the specified location in the specified window 
using the parameters associated with the specified pick context. No pick 
events are generated. Pick highlighting will be performed according to the 
pick highlighting mode and pick highlighting color of the specified pc. 

XPrePick can be used by the graphics application as a visual aid to show 
the user what primitives fall within the pick box boundaries. All graphical 
output primitives that are 1) within the pick box, 2) visible, and 3) pickable, 
according to the value of the current name set and the inclusion/exclusion 
filters, will be drawn in the highlight color. 

Errors 

Bad Alloc (returned if the server is out of memory) 

BadPC 

BadWindow (returned if the window doesn't exist or isn't being used to dis- 
play 3D graphics) 
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XSelectPickEvenfs 
Syntax 
int 

XSelectPickEvents(c/py, win, mask) 
Display *dpy, 

Window win; 

unsigned long mask; 
Arguments 

dpy The display on which you are going to perform a pick. 

win The window in which you are going to pick. 

mask The bitwise logical OR of zero or more of the following: 

PickMask, PickPathMask. 

A mask value of zero means send no events. Having the 
PickMask bit set will cause picking events to be sent. 
Having the PickPathMask bit set will cause pick path 
events to be sent. 

Description 

An XSelectPickEvents call selects the events to be sent by the server when 
a pick occurs. By default, no events will be sent unless they have been 
selected before a pick is requested. 

The pick events mask for a window is analogous to the events mask that 
controls selection of X core events such as ButtonPress or Exposure. A 
limitation of the current implementation is that pick events and pick path 
events may not be propagated up the window hierarchy. Pick events and pick 
path events may only be reported to the window associated with the PHIGS 
workstation for the pick operation. 

Errors 

Bad Window (returned if the window doesn't exist or isn't being used to dis- 
play 3D graphics) *'■ 

BadVaiue (returned if mask bits other than those specified by PickMask and 
PickPathMask are set) 



c 



c 



c 



2 - 44 ESV Workstation Reference Manual [2.0] 



X Extensions 



XSetPickBoxSize 
Syntax 
int 

XSetPickBoxSize(dpy, pc, width, height) 
Display *dpy, 

PC pc, 

int width; 

int height, 

Arguments 

dpy The display on which you are going to perform a pick. 

pc A pick context whose value you are changing. 

width The width of the pick box in pixels. 

height The height of the pick box in pixels. 
Description 

An XSetPickBoxSize call sets the size of the picking box. The default pick 
box size is 9 pixels by 9 pixels. 

The pick box boundaries need not fall evenly on pixel boundaries. The 
screenx and screeny values returned in an XPickEvent are calculated at the 
precision of the floating point hardware in the graphics subsystem. 

Errors 

BadPC 

BadValue (returned if the width or height of the pickbox is less than zero or 
greater than the size of the screen) 
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XSetPickFilters f 

Syntax 
int 

XSetPickFilters(tfpy, pc, Inclusion, exclusion) 
Display *dpy 9 

PC pc, 

XPickFHter inclusion; 

XPickFHter 'exclusion; 

Arguments 

dpy The display on which the PC was created. 

pc A pick context whose value you are changing., 

Inclusion The new inclusion filter. 

exclusion The new exclusion filter. 
Description 

An XSetPickFilters call is used to set a PHIGS-compatible picking filter in a 
picking context. A drawing primitive will be pickable if the intersection of the 
current name set with the inclusion filter is not empty and the intersection of 
the current name set with the exclusion filter is empty. Refer to the ANSI g 

PHIGS specification for more information on name sets. V 

Errors 

BadPC 

BadValue (returned if the number of names in a pick filter is negative or 
greater than an implementation specific limit) 
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XSetPickHighlightingCoIor 

Syntax 

int 

XSetPickHighlightlngGolor(cfpy, pc, coloi) 

Display *dpy; 

PC pc, 

unsigned long color, 

Arguments 

dpy The display on which you are going to perform a pick. 

pc A pick context whose value you are changing. 

color An X pixel value that will determine the highlighting color 

used during a structure traversal (in the form Oxffffff). 

Description 

An XSetPickHighlightingCoIor call sets the pick highlighting color. If high- 
lighting is turned on, pickable items will be highlighted in this color. The de- 
fault highlighting color is white. 

Errors 

BadPC 
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XSetPickHighlightingMode 
Syntax 
int 

XSetPickHighlightingMode(dpy, pc, mode) 
Display *dpy, 



c 



PC 
int 
Arguments 

dpy 

pc 

mode 



PC 
mode; 

The display on which you are going to perform a pick. 

A pick context whose value you are changing. 

One of the following defined constants: 
pick_highlighting_off, pickjiighlightingjtem, 
pickhighlightingcommand. 

pick_highlighting_off turns off all pick highlighting. 
pickjiighlightingjtem causes the marker, line segment, 
or polygon that was picked to be highlighted. 
pick__highlighting_command causes all or part of a 
structure element to be redrawn highlighted. How much is 
redrawn is implementation dependent. 

It is expected that other highlighting modes will be defined. 

Description 

An XSetPickHighlightingMode call sets the pick highlighting mode and 
turns pick highlighting on or off. This pick highlighting mode controls the 
highlighting mode for both pick and prepick operations. Note that a prepick 
operation initiated when the highlighting mode is off is a rather expensive no- 
op. 

Errors 

BadPO 

Bad Value (returned if mode is not one of the defined values) 



( 
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XSetPickMode 



Syntax 

int 

XSetPickMode(dpy, pc, mode) 
Display *dpy, 

PC pc, 

int mode; 



Arguments 
dpy 
pc 
mode 



The display on which you are going to perform a pick. 

A pick context whose value you are changing. 

One of the following defined constants: pickjirst, 
pickjast, plckjiear, or pickjar. 

If the mode is pickjirst, then the first pickable item 
encountered in structure posting is picked. If the mode is 
pickjast, then the last pickable item encountered is picked. 
If the mode is pickjiear, then the pickable item with the 
largest z- value is picked. If the mode is pick Jar, then the 
pickable item with the smallest z-value is picked. 

Description 

An XSetPickMode call sets the picking mode. This controls which of the 
pickable items are reported after a pick operation is initiated. 

Errors 
BadPC 
Bad Value (returned if mode is not one of the defined values) 
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XSetPickReturnVals f 

Syntax ^ 

XSetPickReturnVals(dpy, pc, mask) 
Display *dpy 9 

PC pc, 

unsigned long mask; 
Arguments 

dpy The display on which you are going to perform a pick. 

pc A pick context whose value you are changing. 

mask The logical OR of zero or more the following bits: 

pick_compute_modelpt, pick compute_ special. 

If pick_compute_modelpt is set, the server will attempt to 
calculate a model space point on the picked primitive which 
is within the pick box. If the point cannot be calculated, 
pick_modeipt_valid in the validjlags of the XPickEvent 
will not be set. If pick com puternodelpt is not set, the 
server may not do the extra work necessary to compute the 
model space point, and pick_modelpt_valid in the 
validjlags of the XPickEvent will not be set. 

pick_compute__special is a value reserved for future 
enhancement of the picking extension. 

Description 

An XSetPickReturnVals call sets the desired values to return in an 
XPickEvent. Some of the calculations involved in the XPickEvent structure 
are expensive to compute. Computation of the model space point can involve 
inversion of the transformation matrix. If the client application does not need 
this data, it need not pay the additional computational penalty. This call can 
be used to inform the server that the model space point or the primitive special 



( 



data will not be needed and needn't be calculated. 
Errors 
BadPC 
BadValue (returned if the mask is not an allowable value) 



c 
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X Overlay Functionality 

The X Overlay Functionality provides easy access to the ESV Workstation 
overlay hardware. An example program demonstrating the use of overlay 
planes on the ESV Workstation is found in 
/usr/people/fstest/demo/overlay.e. 

XAIIocOverlayPlanes 

Syntax 

Status 

XAIIocOverlayPlanes(dpy, win, planes) 

Display *dpy, 

Window win; 

unsigned int planes; 

Description 

XAIIocOverlayPlanes allocates overlay planes for a specific window. On the 
ESV Workstation, the total number of overlay planes that can be allocated is 
four. 

These planes are shared with planes that identify PHIGS workstations. 
Each plane allocated for overlay reduces the total number of PHIGS 
workstations by one-half. If all four are allocated for overlay, a maximum 
number of 12 PHIGS workstations will be available. They can be allocated for 
overlay from one to four. 

If too many planes are requested or no planes can be allocated, a 
BadValue or Bad Alloc error is returned. 

Valid overlay pixel values for the window will be to (2 n -1), where n is 
the number of overlay planes. 
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XFreeOverlayPlanes /^ 

Syntax ^ 

Status 
XFreeOverlayPlanes(dpy, win) 

Display *dpy, 

Window win; 

Description 

XFreeOverlayPlanes frees all of the overlay planes allocated for this win- 
dow. This makes the resource available for other applications. 

XStoreOverlayColor 

Syntax 

Status 

XStoreOverlayColor(c/py, win, coiorceil) 

Display *dpy, 

Window win; 

XColor *colorcell; 

Description £ 

XStoreOverlayColor sets the color to be displayed by this pixel value in the 
overlay colormap associated with a window. This routine will return 
Bad Val ue if the color of the pixel cannot be changed or the pixel is not a valid 
pixel for this window. 

Storing the color does not change the color displayed on the screen. To 
actually change the color, you have to install the overlay colormap. 



Pixel value (zero) is the transparent overlay color. 
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XlnstallOverlayColormap 

Syntax 

Status 
XlnstallOverlayColormapfcfpy, win) 

Display *dpy, 

Window win; 

Description 

XlnstallOverlayColormap loads the overlay colormap for a window into the 
hardware colormap. 

XSelectLayer 

Syntax 

Status 

XSelectLayer(cfpy, win, layei) 

Display *dpy, 

Window win; 

int iayer, 

Description 

XSelectLayer selects the layer in which following graphics commands will 
be done. Layer is overlay, and layer 1 is the normal frame buffer. 

Restrictions 

• ES V does not support ALU operation in the overlay planes. This 
means that any X operation with an ALU mode other than GXcopy 
cannot be done. 

• Any X operation that needs both a foreground and a background color 
will not work correctly. The foreground color will j)e written, but the 
background will not. 

• XGetlmage will return the pixels in the currently selected layer. The 
overlay image will be returned in the low order bits of 32 bit pixels. 

• XPutlmage will work when overlay layers are selected. The image 
must be stored in the low order bits of 32 bit pixels. 
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X Multiscreen Functionality 

Having multiple screens can provide a more efficient and organized working 
environment than having a single screen. Multiple screens allow you to effec- 
tively expand your working surface. The term "screen" here means a logical 
screen not a physical one. When displayed, a logical screen takes up the entire 
surface of a monitor. When not displayed, it is not seen. With multiple 
screens, you can configure the windows you would like on each screen and 
then not have to rearrange them (as you do now) if you need to look at a win- 
dow that is buried in a stack or iconified. With the mouse you can switch 
screens to an entirely new screen of different windows. This general interface 
is for handling multiple logical screens (including normal screens, stereo 
screens, etc.). 

The concept of multiple screens has always existed in the XI 1 X Server. 
It provides for having screens that have important different physical qualities, 
such as pixel resolution, number of available bitplanes, or video modes such 
as stereo, PAL, or NTSC. Each screen has an associated screen number. To 
place windows on a given screen call XOpenDisplay with the display string 
parameter containing the screen number. Thus screens are separate and 
distinct from each other. This is analogous to having several physical 
monitors on which to do work. 

It is interesting to note that the screen handling software in the server also 
provides for actually having multiple physical screens on which to do 
graphics. In fact the software in the server at the screen control level does not 
know the difference between a physical screen and a logical one. 

This is an application/user interface which provides a way for you to 
configure logical screens in a spatial order so that you can easily move from 
one screen to the next. It gives the application the ability to warp (move) 
between screens. It gives you the ability to define how the screens are 
conceptually arrayed in a bank of screens. 

Defining the Number of Available Screens 

To specify that more than one screen is wanted, such as for stereo, the 
-nscreens MxN option is used on the command line when the Server is start- 
ed, where Aland N are integers. These arguments should not be too large be- 
cause screens do not come free. The default is 2X2. The screens are 
conceptually laid out side by side in Jtf rows and N columns. For example, if 
you use the option -nscreens 3x4 then the screens will be conceptually 
thought of as: 
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Screen 


Screen 1 


Screen 2 


Screen 3 


Screen 4 


Screen 5 


Screen 6 


Screen 7 


Screen 8 


Screen 9 


Screen 10 


Screen 1 1 



Defining Stereo Screens 

To identify a screen as a stereo screen with square pixels, the option 
stereoscr num is used. Screens are numbered beginning at 0, and screen 
is the first one displayed when the server comes up. There can be more than 
one stereo screen. Screen can be a regular screen or a stereo screen. 

To identify a screen as a stereo screen with tall, skinny pixels, the option 
-stereotallscr num is used. 

Moving from Screen to Screen 

There are different ways provided to move between screens. 

1) You can use the mwm menu or the csm X client. See the man pages for 
these in the "X Clients" chapter of the ESV Workstation Reference 
Manual 

2) You can use the cursor, assuming XScreenWarpByCursor has been en- 
abled (see below). 

Logical screens are conceptually laid out as pictured above. You can 
switch between logical screens by moving the cursor off the side of the 
physical screen in the direction of the new logical screen. For example, in 
the configuration above, if you want to go from Screen to Screen 4, you 
move the cursor off the bottom of Screen and Screen 4 will be displayed. 
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Also, the cursor will wrap in moving between screens so that if you are m 

on Screen 3 you can go to Screen by moving the cursor off the right edge V_ 

of Screen 3. 

3) To change screens through program control, call the extension function 

XWarpToScreen (display, screen_num) ; 
where screenjnum is an integer that defines which screen to display. 

Enabling and Disabling Moving Between Screens Via the Cursor 

There may be times when you want to disable changing screens using the 
cursor. This can be done by the extension call 

XScreenWarpByCursor (display, enable_flag) ; 

where enable Jflag can be 

True - Enable screen switch by cursor. 

False - Disable screen switch by cursor. 

The default condition of this parameter is false, which means that the 
server will not switch screens via cursor movement unless the capability is 
turned on using this call. 

Inquiring Information about Screens 

X clients may want to know specific items about available screens such as the f 

MxN configuration and screen types. This information can be obtained using \^ 

the following extension 

XGetScreensInfo (display, screen_info) ; 
Display ^display; 
Screenlnfo **screen_info; 

where the routine returns a Screenlnfo structure that looks like this. 

typedef struct _ScreenInfo_ { 

int numof screens; /* num of screens in the server */ 

int config_M; /* num of rows of screens */ 

int config_N; /* num of columns of screens */ 

struct { /* An array of structures of screen info */ 

int screennum; /* num of screen */ 

int screentype; /* screen type */ 

int rootvisual; /* visual type of root window */ 

int screen_subtypel; /* reserved, not used */ 

int monitor; /* which physical monitor screen is on */ 

} screens [numof screens] ; 

} Screenlnfo; 

Once the application is finished looking at this information, it should 
deallocate the structure by calling 

XFreeScreenlnfo (screen_info) ; m 
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XFreeScreenslnfo 
Name 



XFreeScreenslnfo - X extension function to deallocate the xScreensInf o 
structure 

Syntax 

#include <XMultiScreen.h> 

int XFreeScreensInf o(screenJnfo) 

xScreenslnfo *screen_info; 

where the xScreenslnfo structure has been created by and returned from a 
call to XGetScreenslnfo. 

Description 

This X extension routine is part of the ESV Multiscreen extension for han- 
dling multiple screens in the X Server. XFreeScreenslnfo is a function de- 
signed to free the information buffer that is returned from the function 
XGetScreenslnfo. The client is responsible to call this routine to deallocate 
the memory used. 

Related Files 

XWarpToScreen 

XScreenWarpByCursor 

XGetScreenslnfo 

Xesv (-nscreens option) 

csm (a screen manager client for warping between screens) 
Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 
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XGetScreensInfo 
Name 



XGetScreensInfo - X extension reply to return information to the client 
about the number and type of available screens. 

Syntax 

include <XMultiScreen.h> 

int XGetScreens(nfo(dpy, screenjnfo) 
Display *dpy, 

xScreenslnfo ** screenjnfo; 

where the Scree nslnfo structure is defined by the following types: 

typedef struct _xOneScreen_ { 
int screennum; /* Screen number */ 

int screentype; /* Screen Type: xDefaultScreen, etc. */ 

int rootvisual; /* visual type of root window */ 

int screen_subtype1; /* reserved, not used */ 
int monitor, /* which monitor screen is assigned to */ 

} xOneScreen; 

typedef struct _xScreenslnfo__ { 

int numofscreens; /* Number of available screens */ 

int rowsofscreens; /* Number of "Rows" of screens */ 

int colsofscreens; /* Number of "Columns" of screens */■ 

xOneScreen screens[\]; /* Variable length array of screens. */ 

} xScreenslnfo; 

Description 

This X extension routine is part of the ESV Multiscreen extension for han- 
dling multiple screens in the X Server. XGetScreensInfo is a function de- 
signed to give clients information about the number and type of screens 
available in a given server. 

Screen Types 

The screen type is returned in the screentype field of the return argument. 
The possible screen types are defined by the following constants: 

• xDefaultScreen 

The standard screen, 1280 x 1024 pixels. 
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• xStereoScreen Stereo 

Video format, 640 x 512 pixels. 

• xStereoTallScreen Stereo 
Video format, 1280 x 512 pixels. 

Visual Types 

The visual type of the screen's root window is returned in the root visual field 
of the return argument. The possible visual types of root windows of screens 
are defined by standard X constants: 

TrueColor 

The root window is a 24 bit True Color window (the default). 

DirectColor 
The root window is a 24 bit Direct Color window. 

Pseudocolor 
The root window is an 8 bit Pseudo Color window. 

Note: The default Direct Color and Pseudo Color 

types are not gamma corrected. This causes 

their colors to be slightly different from the 

True Color type. 
Screen Rows and Columns 

In the ESV X Server, the available screens are conceptually arranged in a 
rectangular grid. This routine also returns the number of rows and columns in 
the grid in the rowsofscreens and the colsofscreens fields of the return ar- 
gument. When moving between screens by moving the cursor off-screen, the 
screen moved to is the next one in the row or column that adjoins the side of 
the screen that the cursor moved off of. 

The Screen Number 

Each screen is identified by a non-negative integer. The screen's number is 
returned in the screennum field of the return argument. Screens are num- 
bered consecutively from left to right beginning with the first row. The first 
screen in the first row is Screen 0. 

Free the Return Buffer 

The returned information is stored in a buffer pointed to by the screen_info 
argument. This buffer is allocated by the routine at runtime and should be 
deallocated by the application calling XFreeScreensinfo. 
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Return Value 

If there is an error during the processing of this request, XGetScreenslnfo 
will return a 0; if successful it will return 1. 

Related Files 

XWarpToScreen 

XScreenWarpByCursor 

XFreeScreenslnfo 

Xesv (-nscreens option) 

csm (a screen manager client for warping between screens) 
Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 
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XScreenWarpByCursor 
Name 



XScreenWarpByCursor - X extension request to enable or disable switching 
screens by moving the cursor off-screen, on the 
monitor. 

Syntax 

#include <XMultiScreen.h> 

int XScreenWarpByCursor(d|py, enable) 
register Display *dpy, 
unsigned Bool enable; 

Description 

This X extension routine is part of the ES V Multiscreen extension for 
handling multiple screens in the X Server. XScreenWarpByCursor is a 
function designed to allow clients to enable or disable the ability to change 
screens by moving the cursor off-screen. If the argument enable is passed as 
true, the ability is enabled, if false, the ability is disabled. When warping 
between screens by the cursor has been disabled, the displayed screen can 
only be switched by an active client calling XWarpToScreen. 

Return Value 

If there is an error during the processing of this request, 
XScreenWarpByCursor will return a 0; if successful it will return 1. 

Errors 

If an invalid value for enable is passed to this function, the server will return 
a BadScreenWarpByCursor error and will ignore the request. 

Related Files 

XWarpToScreen 

XGetScreenslnfo 

XFreeScreenslnfo 

Xesv (-nscreens option) 

csm (a screen manager client for warping between screens) 
Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 
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XWarpToScreen 



Name ^ 

XWarpToScreen - X extension request to display a different "screen" on the 
monitor. 

Syntax 

#include <XMultiScreen.h> 

int XWarpToScreen(cfpy, screennum, x, y) 
register Display *dpy, 

unsigned long screennum; 

int x; 

int y\ 

Description 

This X extension routine is part of the ESV Multiscreen extension for han- 
dling multiple screens in the X Server. XWarpToScreen is a function de- 
signed to allow clients to switch the display from the currently displayed 
screen to a new screen identified by screennum. In addition, the cursor po- 
sition on the new screen is identified by the x and y arguments. 

Return Value | 

If there is an error during the processing of this request, XWarpToScreen 
will return a 0; if successful it will return 1. 

Errors 

If an invalid screen number is passed to this function, the server will return a 
BadWarpToScreen error and will ignore the request. 

Related Files 

XScreenWarpByCursor 

XGetScreenslnfo 

XFreeScreenslnfo 

Xesv (-nscreens option) 

csm (a screen manager client for warping between screens) 
Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 

Copyright (c) 1990 by Sun Microsystems, Inc. and the X Consortium. 

All Rights Reserved 



( 
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X Video Timing Formats Functionality 

XVideoMode 

Name 

XVideoMode - X extension to change the ES V video format of the monitor 
and video hardware. 

Syntax 

#include <XVideoMode.h> 

int XVideoMode(c//sp/ay, videoMode) 

register Display *dispiay, 

unsigned long videoMode; 

Arguments 

display The connection to the server. 

videoMode One of the following constants: 

Monoscopic (default video mode, pixels 1280x1024) 

RS_343_A_1280xl024 

RS_343_A_1 260x946 

PAL_SECAM_768x574 

RS_170_A_640x480 

Stereo60KHzIntStorl280xl024 

Stereo60KHzSplitStorl280xl024 

Stereo60KHzIntStor640xl024 

Stereo60KHzSplitStor640xl024 

Description 

This X extension routine is designed to allow clients to switch the ES V work- 
station to various possible video formats. Many of the formats have pixel res- 
olutions that are different from the default monoscopic resolution of 
1280 x 1024. As a result, they do not work well with the ESV X Server. Not 
all of the formats make sense in terms of using the ESV monitor for display. 
The stereo formats are generally not accessed via this interface but can be bet- 
ter used by setting up stereo screens when the X Server is started (see the man 
page on Xesv). 
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Return Value 

If there is an error during the processing of this request, XVideoFormat will 
return a 0; if successful it will return 1. 

Errors 

If an invalid video format is requested, the server will return a 
Bad Video Mode error and ignore the request. 

Related Files 

Xesv 

Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 
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X Miscellaneous Traversal Functionality 

There are two different types of X extensions that are in the miscellaneous tra- 
versal category. One extension is used to inquire traversal data from the PEX 
server. The other redraws a 3D PHIGS image and keeps it displayed for a 
specified amount of time. 

XGetTraversallnfo allows you to retrieve information about user-defined 
IDs in GSE Information nodes and the current state of the transformation 
matrices at points in the PHIGS structure. This information is valuable for 
molecular modeling applications. 

XFreeTraversallnfo frees the memory allocated by XGetTraversallnfo 
and should be called by the application after each XGetTraversallnfo call. 

XRedrawDelaySD gives you increased control over the timing of the 
PHIGS/PEX 3D updates. This is used primarily in animation applications. 
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XFreeTraversallnfo 



c 

Name 

XFreeTraversallnfo - Free the memory allocated by XGetTraversallnfo for 
its return buffers. 

Syntax 

#include <XTrav3D.h> 

XfreeTraversallnfo(frav_d0fa) 

PEXTravData *tmv_data; 

where the PEXTravData structure is defined as: 
typedef struct _PEXTravData { 

Int num_entries a , /* Number of data records in the return. */ 

char "entries; /* Pointer to the return data */ 
} PEXTravData; 
Description 

This routine frees the memory that is allocated by the X extension 
XGetTraversallnfo. See the manual page for XGetTraversallnfo for com- 
plete information on the extension and its purpose. 

Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation . 



c 
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XGetTraversallnfo 
Name 



XGetTraversallnfo - X extension to inquire traversal data from the 
PEX server. 

Syntax 

#include <XTrav3D.h> 

int XGetTraversallnfo(cfpy, win, travjnfo) 
register Display *dpy, 

Window win; 

PEXTravinf o ** travjnfo; 

Arguments 

display The connection to the server. 

window The window ED associated with the 3D PHIGS work- 

station. 

travjnfo The returned traversal data of type PEXTravData, 

where the PEXTravData structure is defined as: 

typedef struct _PEXTravData { 

int num_entries; /* Number of data records in the return */ 

char * entries; /* Pointer to the return data */ 

} PEXTravData; 

Description 

This X extension reply routine is part of a special functionality that allows ap- 
plications to retrieve certain types of traversal state information from the PEX 
server's structure walker. Essentially, the returned information consists of (1) 
user-defined IDs placed in GSE Information nodes in the application's PHIGS 
structure, and (2) the current state of the composite local and global PHIGS 
transformation matrices at points in the PHIGS structure designated, again, by 
an Information GSE. The IDs allow the application to develop a relationship 
between a given matrix and primitives of interest. This provides a way for 
molecular modeling applications to do distance monitoring and energy calcu- 
lations by supplying them access to transformation matrices which can then 
be used to calculate point positions. Also, this functionality could conceiv- 
ably be used to do collision detection. 

New PHIGS GSE Node: Information Node 

To retrieve traversal-time state information from the Server, the application 
must add Information GSE nodes at points of interest within the PHIGS struc- 
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ture. Upon traversal of an Information GSE node during a speci al information g 

traversal (invoked by XGetTraversallnfo), the information requested will be v^ 

buffered and returned to the application. These special nodes are ignored dur- 
ing regular traversals. 

The Information GSE has a node type of PES_GSEJNFORMATION. 

(The value of this constant depends on the current implementation and may 
change. The PHIGS application developer should only use the above name 
and not its value when writing source code.) The data structures supporting 
this GSE are defined by: 



typedef enum { 




PES_INFORMATION_MATRIX, 




PES_INFORMATION_ID 




} Pes information type; 




typedef struct { 




Pes__information type 


type; 


union { 




int 


unused; 


int 


id; 


} rec; 





} Pinformation_data; 

The Pinformation_data structure is pointed to by the data field of a f 

Pdata structure and the size field is set to the sizeof (Pinfomiation data) v 

These definitions are found in esgdp.h. 

The definition of the Pdata structure is in phigs.h: 



typedef 


struct 


{ 








size_t 


size; 


/* size of 


data */ 




char 


*data; 


/* pointer 


to data */ 


} Pdata; 










An example of 
GSE would be: 


coding a PHIGS application to include the Information 



#include <phigs.h> 
#include <esgdp.h> 
#include <XTrav3D.h> 

Pdata gse_data; 

Pinformation data *info; 



gse_data .size = (size_t) sizeof (Pinformation_data) 
gse_data.data = malloc ( (int) gse_data .size) ; 



C 
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info = (Pinformation_data *) gse_data .data; 
info->type = PES_INFORMATION_MATRIX; 
pgse (PES_GSE_INFORMATION, &gse_data) ; 



Requesting the Special Informational Traversal 



After the PHIGS structure has been built, the application can request a special 
information traversal by calling XGetTraversallnfo. (See the syntax above 
for its arguments.) The special information traversal invoked by 
XGetTraversallnfo does not produce any graphical output. The Server will 
traverse the structure, maintain the matrix stack and generate the information 
return buffers as dictated by the special GSE nodes in the structure. 

The data being returned is pointed to by the entries field in the 
PEXTravData structure that is returned by XGetTraversallnfo. The data is of 
the following format: 



1st 


data type 


1st 


data 


• 


nth data type 


nth 


data 



matrix or ID type: 

PES_INFORMATION_MATRIX or 
PES_INFORMATION_ID 

matrix data or ID 



matrix or ID type: 

PES_INFORMATION_MATRIX or 
PES_INFORMATION_ID 

matrix data or ID 



For convenience we will define the following structure types to aid in 
processing individual records within the data: 

typedef struct _PEXTraverseMatrix { 

unsigned long type; 

Pmatrix3 matrix; 

} PEXTraverseMatrix; 

typedef struct _PEXTraverseId { 

unsigned long type; 

unsigned long id; 

} PEXTraverseld; 
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Return Value 

If there is an error during the processing of this request, XGetT reversal Info 
will return a 0; if successful it will return 1. 

Freeing the Return Buffer 

Once the return data has been processed, the client is responsible to deallocate 
the return buffer memory by calling: 

Xf reeTraversallnf o (trav_data) 

PEXTravData *trav_data; 

Related Files 

XFreeTraversallnfo(3X) 
Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation, 
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XRedrawDelaySD 
Name 

XRedrawDelaySD - X extension to redraw a 3D PHIGS image and keep it dis- 
played for at least a given amount of time. 

Syntax 

#include <XTrav3D.h> 

int XRedrawDelay3D(dpy, win, delay) 

register Display *dpy 3 

Window win; 

int delay; 

Arguments 

display The connection to the server. 

win The window ID associated with the 3D PHIGS workstation. 

delay The number of vertical retraces ( 1/60^ of a second) to delay 

before allowing another buffer swap to occur in a given 3D 
window after the redraw caused by this request takes place. 
After the delay period has passed, another redraw in the win- 
dow will be allowed if one has been requested. If this argu- 
ment is set to XDelayCancel, and if there is a previously 
processed RedrawDelay3D request whose delay time has 
not yet expired, then the delay time is immediately set to 
zero, and a new redraw is requested. 

Description 

This X extension is part of a special functionality that supports animation ap- 
plications. It gives the application an increased amount of control over the 
timing of PHIGS/PEX 3D redraws or updates. 

This function first causes a PHIGS UPDATE_WORKSTATION to occur. 
Then, if the delay argument is greater than or equal to zero, this function 
causes a REDRAW_ALL_STRUCTURES to occur, and the newly updated 
buffer is displayed on the screen and will remain until at least the delay 
number of monitor refreshes ( 1/60 s) has occurred, after which another image 
update and buffer swap will be allowed. 

If the delay argument is equal to DelayCancel, and if a redraw delay time 
is still in effect for this window from a previous RedrawDelay3D request, the 
delay time is reset to and a REDRAW_ALL_STRUCTURES is requested. 
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The application programmer should consider the following facts in using m 

this capability: V_ 

1) Applications doing animations that do not require precise frame rates 
can perform adequately by using available UNIX timing capabilities. To 
simultaneously handle user interactions that effect the animation image, 
the application can use the XSync function to wait until a 
REDRAW_ALL_STRUCTURES or an UPDATE_WORKSTATION 
request is complete. This allows the application to avoid queueing up 
large numbers of redraw requests or update workstation requests. A 
large queue of pending updates or redraws would prohibit immediate 
picture changes to reflect peripheral interaction, such as dial turns, 
because the previously requested redraws would have to be processed 
first. After calling XSync, the application is blocked until traversal is 
complete. This assures that the application will never queue more than 
one update request in addition to the two frames that already are in the 
frame buffer. 

2) Applications that require precise frame rates can use the 
RedrawDelaySD request to precisely control the animation frame rate, 
as long as the frame complexity does not exceed the ES V hardware 
capabilities, that is, as long as the next frame to be displayed can be 
generated in less time than the redraw delay time. 

3) Even when using RedrawDelaySD requests, the application will prob- ■ 
ably want to be able to handle user interactions that change the 3D im- ^ 
age while the animation is running. Once again, if multiple 
RedrawDelaySD requests have been queued up, they will have to be 
processed first by the server and graphics hardware before affects from 

any user interaction can be displayed, thus destroying the feel of inter- 
activity. To avoid queueing up multiple RedrawDelaySD requests the 
application can wait on a call to XSync, or it can use XSync combined 
with UNIX timers to determine the approximate traversal time of a 
workstation and then avoid issuing RedrawDelaySD requests more of- 
ten than the ES V can keep up with. It is a burden on the application to 
ensure that the RedrawDelaySD requests come in at an appropriate rate. 

4) To aid in handling user interactions, a single previously requested 
RedrawDelaySD request can be caused to terminate prematurely by 
passing the constant XDelayCancel in the delay argument. This sets 
the delay timer to zero and allows other redraw requests to be processed 
by the graphics hardware. However if several Redraw or RedrawDelay 
requests have been queued up, then the Redraw that is requested by this 
invocation of RedrawRequestSD will not be processed until the other 
requests have first been processed. 



C 
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5) Only one PHIGS workstation may do a RedrawDelaySD request at a 
time. If multiple workstations do it, there is no guarantee as to the re- 
sponse of the system. Neither one will animate at the correct rate. 

Return Value 

If there is an error during the processing of this request, XRedrawDelay3D 
will return a 0; if successful it will return 1. 

Copyright 

Copyright 1990, Evans and Sutherland Computer Corporation. 
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3. X Clients 



Introduction 



Following is a list of the X Clients supported on the ES V Workstation. The 
documentation for most of these clients can be found in the X Window System 
User's Guide, published by O'Reilly & Associates. On-line manpage docu- 
mentation is available for those not found in the O'Reilly & Associates book. 



appres 


atobm 


bdftosnf 


bitmap 


bmtoa 


csm 


editres 


esvipc 


ico 


listres 


maze 


mkfontdir 


muncher 


mwm 


oclock 


pexscope 


plaid 


puzzle 


resize 


screen 


sessreg 


showrgb 


showsnf 


startesvx 


startx 


uil 


xauth 


xbiff 


xcalc 


xclipboard 


xclock 


xcm 


xcutsel 


xdm 


xdmshell 


xdpyinfo 


xedit 


xev 


xeyes 


xfd 


xfontsel 


xhost 


xinit 


xkill 


xload 


xlock 


xlogo 


xlsatoms 


xlsclients 


xlsfonts 


xlswins 


xmag 


xman 


xmh 


xmodmap 


xprop 


xrdb 


xrefresh 


xset 


xsefpointer 


xsetroot 


xstdcmap 


xterm 


xwd 


xwdrle 


xwininfo 


xwud 
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This chapter documents the following which are specific to the ESV 
Workstation: 

X - a portable, network-transparent window system 

Xesv - X Version 1 1 server for ESV Series Workstations 

xcm - an X client manager provides access via menus 

csm - Multiscreen manager for X servers supporting multiple screens 

mwm - Motif window manager 



( 



( 
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Name 

X - a portable, network-transparent window system 

Syntax 

The X Window System is a network-transparent window system developed 
at the Massachusetts Institute of Technology (MIT) which runs on the ESV 
Workstation. The X Consortium requests that the following names be used 
when referring to this software: 

X 

X Window System 

X Version 1 1 

X Window System, Version 1 1 

Xll 

X Window System is a trademark of MIT. 

Description 

X Window System servers run on computers with bitmap displays. The server 
distributes user input to and accepts output requests from various client 
programs through a variety of different interprocess communication 
channels. Although the most common case is for the client programs to be 
running on the same machine as the server, clients can be run transparently 
from other machines (including machines with different architectures and 
operating systems) as well. 

X supports overlapping hierarchical subwindows and text and graphics 
operations, on both monochrome and color displays. For a full explanation of 
the functions that are available, see the Xlib - C Language X Interface manual, 
the X Window System Protocol specification, the X Toolkit Intrinsics - C 
Language Interface manual, and Various toolkit documents. 

The number of programs that use X is growing rapidly. Of particular 
interest are: a terminal emulator (xterm), a window manager (mwm), a 
display manager (xdm), a mail managing utility (xbiff ), a manual page 
browser (xman), a bitmap editor (bitmap), access control programs (xauth 
and xhost), user preference setting programs (xmodmap, xrdb, xset, and 
xsetroot), a clock (xclock), a font displayer (xfd), utilities for listing 
, information about fonts, windows, and displays (xdpyinfo, xfontsel, 
xlsfonts, xlswins, xwininfo, xlsclients, and xprop), and screen image 
manipulation utilities (xmag, xpr, xwd, and xwud). 

See your site administrator for other utilities, window managers, games, 
toolkits, etc., available from user-contributed software. 
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Starting Up 

There are two main ways of getting the X server and an initial set of client 
applications started. The particular method used depends on what operating 
system you are running and on whether or not you use other window systems 
in addition to X. 

• xdm (the X Display Manager) 

If you want to always have X running on your display, your site 
administrator can set your machine up to use the X Display Manager 
xdm. This program is typically started by the system at boot time and 
takes care of keeping the server running and getting users logged in. 
If you are running xdm, you will see a window on the screen 
welcoming you to the system and asking for your username and 
password. Simply type them in as you would at a normal terminal, 
pressing the RETURN key after each. If you make a mistake, xdm will 
display an error message and ask you to try again. After you have 
successfully logged in, xdm will start up your X environment. By 
default, if you have an executable file named .xsession in your home 
directory, xdm will treat it as a program (or shell script) to run to start 
up your initial clients (such as terminal emulators, clocks, a window 
manager, user settings for things like the background, the speed of the 
pointer, etc.). Your site administrator can provide details. 

• xinit (run manually from the shell) 

Sites that support more than one window system might choose to use 
the xinit program for starting X manually. If this is true for your 
machine, your site administrator will probably have provided a 
program named x1 1 , startx, or xstart that will do site-specific 
initialization (such as loading convenient default resources, running a 
window manager, displaying a clock, and starting several terminal 
emulators) in a nice way. If not, you can build such a script using the 
xinit program. This utility simply runs one user- specified program to 
start the server, runs another to start up any desired clients* and then 
waits for either to finish. Since either or both of the user-specified 
programs may be a shell script, this gives substantial flexibility at the 
expense of a nice interface. For this reason, xinit is not intended for 
end users. 

Display Names 

From the user's prospective, every X server has a display name of the form: 
hostname:dispiaynumber.screennumher 

This information is used by the application to determine how it should 
connect to the server and which screen it should use by default (on displays 
with multiple monitors): 
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• hostname 

The hostname specifies the name of the machine to which the display 
is physically connected. If the hostname is not given, the most 
efficient way of communicating to a server on the same machine will 
be used. 

• dlsplaynumher 

The word "display" is usually used to refer to collection of monitors 
that share a common keyboard and pointer (mouse, tablet, etc.). Most 
workstations tend to only have one keyboard, and therefore, only one 
display. Larger, multi-user systems, however, will frequently have 
several displays so that more than one person can be doing graphics 
work at once. To avoid confusion, each display on a machine is 
assigned a display number (beginning at 0) when the X server for that 
display is started. The dlsplaynumher must always be given in a 
display name. 

• screennumber 

Some displays share a single keyboard and pointer among two or 
more monitors. Since each monitor has its own set of windows, each 
screen is assigned a screennumber (beginning at 0) when the X 
server for that display is started. If the screennumber is not given, 
then screen will be used. 

On POSIX systems, the default display name is stored in your DISPLAY 
environment variable. This variable is set automatically by the xterm 
terminal emulator. However, when you log into another machine on a 
network, you'll need to set DISPLAY by hand to point to your display. For 
example, 

% setenv DISPLAY myws : 

$ DISPLAY=myws:0; export DISPLAY 

Finally, most X programs accept a command line option of -display 
dlsplayname to temporarily override the contents of DISPLA Y. This is most 
commonly used to pop windows on another person's screen or as part of a 
remote shell command to start an xterm pointing back to your display. For 
example, 

% xeyes -display joesws:0 -geometry 1000x1000+0+0 
% rsh big xterm -display myws : -Is </dev/null & 

X servers listen for connections on a variety of different communications 
channels (network byte streams, shared memory, etc.). Since there can be 
more than one way of contacting a given server, the hostname part of the dis- 
play name is used to determine the type of channel (also called a transport 
layer) to be used. The sample servers from MIT support the following types 
of connections: 



ESV Workstation Reference Manual [2.0] 3 - 5 



X Clients 



• local 

The hostname part of the display name should be the empty string. 
For example, : , : 1 , and : . 1 . The most efficient local 
transport will be chosen. 

• TCP/IP 

The hostname part of the display name should be the server 
machine's IP address name. Full Internet names, abbreviated names, 
and IP addresses are all allowed. For example: 

expo.lcs.mit .edu:0, expo:0, 18.30.0.212:0, bigmachine : 1, 

and 

hydra : . 1 . 

• DECnet 

The hostname part of the display name should be the server 
machine's nodename followed by two colons instead of one. For 
example, 

myws::0, big::l, and hydra:: 0.1. 

Access Control 

The sample server provides two types of access control: an authorization pro- 
tocol which provides a list of magic cookies clients can send to request access, 
and a list of hosts from which connections are always accepted, xdm initial- 
izes magic cookies in the server, and also places them in a file accessible to 
the user. Normally, the list of hosts from which connections are always ac- 
cepted should be empty, so that only clients which are explicitly authorized 
can connect to the display. When you add entries to the host list (with xhost), 
the server no longer performs any authorization on connections from those 
machines. Be careful with this. 

The file for authorization used by both xdm and Xlib can be specified with 
the environment variable XAUTHORITY, and defaults to the file .Xauthority 
in the home directory, xdm uses $HOME/.Xauthority and will create it or 
merge in authorization records if it already exists when a user logs in. 

To manage a collection of authorization files containing a collection of 
authorization records use xauth. This program allows you to extract records 
and insert them into other files. Using this, you can send authorization to 
remote machines when you log in. As the files are machine-independent, you 
can also simply copy the files or use NFS to share them. If you use several 
machines, and share a common home directory with NFS, then you never 
really have to worry about authorization files, the system should work 
correctly by default. 



( 
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Note: Magic cookies transmitted "in the clear" over NFS or 
using ftp or rep can be "stolen" by a network 
eavesdropper, and as such may enable unauthorized 
access. In many environments this level of security is 
not a concern, but if it is, you need to know the exact 
semantics of the particular magic cookie to know if this 
is actually a problem. 
One of the advantages of using window systems instead of hardwired 
terminals is that applications don't have to be restricted to a particular size or 
location on the screen. Although the layout of windows on a display is 
controlled by the window manager that the user is running (described below), 
most X programs accept a command line argument of the form 

-geometry WIDTHxHEIGHT+XOFF+YOFF 
(where WIDTH, HEIGHT, XOFF, and YOFF are numbers) for specifying a 
preferred size and location for this application's main window. 

The WIDTH and HEIGHT parts of the geometry specification are usually 
measured in either pixels or characters, depending on the application. The 
XOFF and YOFF parts are measured in pixels and are used to specify the 
distance of the window from the left or right and top and bottom edges of the 
screen, respectively. Both types of offsets are measured from the indicated 
edge of the screen to the corresponding edge of the window. 

The jc-offset may be specified in the following ways: 

• +XOFF 

The left edge of the window is to be placed XOFF pixels in from the 
left edge of the screen (i.e., the x-coordinate of the window's origin 
will be XOFF). XOFF may be negative, in which case the window's 
left edge will be off the screen. 

• -XOFF 

The right edge of the window is to be placed XOFFpixels in from the 
right edge of the screen. XOFF may be negative, in which case the 
window's right edge will be off the screen. 

The ^-offset has similar meanings: 

• +YOFF 

The top edge of the window is to be YOFF pixels below the top edge 
of the screen (i.e., the y-coordinate of the window's origin will be 
YOFF). YOFFmay be negative, in which case the window's top edge 
will be off the screen. 
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• -YOFF 

The bottom edge of the window is to be YOFF pixels above the 
bottom edge of the screen. YOFF may be negative, in which case the 
window's bottom edge will be off the screen. 

Offsets must be given as pairs; in other words, in order to specify either 
XOFFot YOFF both must be present. Windows can be placed in the four 
corners of the screen using the following specifications: 

• +0 + upper left hand corner. 

• -0 + upper right hand corner. 

• -0-0 lower right hand corner. 

• +0-0 lower left hand corner. 

In the following examples, a terminal emulator will be placed in roughly 
the center of the screen and a load average monitor, mailbox, and clock will 
be placed in the upper right-hand corner: 

xterm -fn 6x10 -geometry 80x24+30+200 & 
xclock -geometry 48x48-0+0 & 
xload -geometry 48x48-96+0 & 
xbiff -geometry 48x48-48+0 & 

Window Managers 

The layout of windows on the screen is controlled by special programs called 
window managers. Although many window managers will honor geometry 
specifications as given, others may choose to ignore them (requiring the user 
to explicitly draw the window's region on the screen with the pointer, for ex- 
ample). 

Since window managers are regular (albeit complex) client programs, a 
variety of different user interfaces can be built. The core distribution comes 
with a window manager named twm which supports overlapping windows, 
popup menus, point-and-click or click-to-type input models, title bars, nice 
icons, and an icon manager for those who don't like separate icon windows. 

Several other window managers are available in the user-contributed 
software: gwm, m_swm, olwm, and tekwm. 

Collections of characters for displaying text and symbols in X are known 
as fonts. A font typically contains images that share a common appearance 
and look nice together (for example, a single size, boldness, slant, and 
character set). Similarly, collections of fonts that are based on a common type 
face (the variations are usually called roman, bold, italic, bold italic, oblique, 
and bold oblique) are called families. 

Sets of font families of the same resolution (usually measured in dots per 
inch) are further grouped into directories (so named because they were 
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initially stored in file system directories). Each directory contains a database 
which lists the name of the font and information on how to find the font. The 
server uses these databases to translate/b/zf names (which have nothing to do 
with file names) into font data. 

The list of font directories in which the server looks when trying to find a 
font is controlled by the font path. Although most installations will choose to 
have the server start up with all of the commonly used font directories, the 
font path can be changed at any time with the xset program. However, it is 
important to remember that the directory names are on the server's machine, 
not on the application's. 

The default font path for the sample server contains three directories: 

• /usr/lib/X11/fonts/mlsc 

This directory contains many miscellaneous fonts that are useful on 
all systems. It contains a small family of fixed- width fonts in pixel 
heights 5 through 10, a family of fixed- width fonts from Dale 
Schumacher in similar pixel heights, several Kana fonts from Sony 
Corporation, a Kanji font, the standard cursor font, two cursor fonts 
from Digital Equipment Corporation, and OPEN LOOK™ cursor 
and glyph fonts from Sun Microsystems. It also has font name aliases 
for the font names fixed and variable. 

• /usr/iib/X11/fonts/75dpi 

This directory contains fonts contributed by Adobe Systems, Inc., 
Digital Equipment Corporation, Bitstream, Inc., Bigelow and 
Holmes, and Sun Microsystems, Inc. for 75 dots per inch displays. An 
integrated selection of sizes, styles, and weights are provided for each 
family. 

• /usr/iib/X11 /fonts/1 00dpi 

This directory contains 100 dots per inch versions of some of the fonts 
in the 75dpi directory. 

Font databases are created by running the mkfontdir program in the 
directory containing the source or compiled versions of the fonts (in both 
compressed and uncompressed formats). Whenever fonts are added to a 
directory, mkfontdir should be rerun so that the server can find the new fonts. 
To make the server reread the font database, reset the font path with the xset 
program. For example, to add a font to a private directory, the following 
commands could be used: 

% cp newf ont . snf ~/myfonts 
% mkfontdir ~/myfonts 
% xset fp rehash 
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The xlsfonts program can be used to list all of the fonts that are found in 
font databases in the current font path. Font names tend to be fairly long as 
they contain all of the information needed to uniquely identify individual 
fonts. However, the sample server supports wildcarding of font names, so the 
full specification 

-adobe-courier-medium-r-normal — 10-100-75-75-m-60-iso8859-l 

could be abbreviated as: 

-*-courier-medium-r-normal — *-l 00-*-* -*-*-*-* 

or, more tersely (but less accurately): 

*-courier-medium-r-normal — *-100-* 

Because the shell also has special meanings for * and ?, wildcarded font 
names should be quoted: 

% xlsfonts -fn ' * -courier -medium- r-normal — *-100-*' 

If more than one font in a given directory in the font path matches a 
wildcarded font name, the choice of which particular font to return is left to 
the server. However, if fonts from more than one directory match a name, the 
returned font will always be from the first such directory in the font path. The 
example given above will match fonts in both the 75dpi and 100dpi 
directories; if the 75dpi directory is ahead of the 1 00dpi directory in the font 
path, the smaller version of the font will be used. 

Color Names 

Most applications provide ways of tailoring (usually through resources or 
command line arguments) the colors of various elements in the text and 
graphics they display. Although black-and-white displays don't provide 
much of a choice, color displays frequently allow anywhere between 16 and 
16 million different colors. 

Colors are usually specified by their commonly-used names (for example, 
red, white, or medium slate blue). The server translates these names into 
appropriate screen colors using a color database that can usually be found in 
/usr/lib/X11/rgb.txt. Color names are case-insensitive, meaning that red, 
Red, and RED all refer to the same color. 

Many applications also accept color specifications of the following form: 

#rgb 

#rrggbb 

#rrrgggbbb 

# r r r r ggggbbbb 

where r, g, and b are hexadecimal numbers indicating how much red, green, 
and blue should be displayed (zero being none and f f f f being on full). Each 
field in the specification must have the same number of digits (e.g., #rrgb 
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or #gbb are not allowed). Fields that have fewer than four digits (e.g., #rgb) 
are padded out with zero's following each digit (e.g., #r OgO ObO 0). 
The eight primary colors can be represented as: 

black #000000000000 (no color at all) 

red #ffff00000000 

green #0000ff ffOOOO 

blue #00000000ffff 

yellow #ffffffff0000 (full red and green, no blue) 

magenta #f f f fOOOOfff f 

cyan #0000fff fffff 

white #ffffffffffff (full red, green, and blue) 

Unfortunately, RGB color specifications are highly unportable since 
different monitors produce different shades when given the same inputs. 
Similarly, color names aren't portable because there is no standard naming 
scheme and because the color database needs to be tuned for each monitor. 
Application developers should take care to make their colors tailorable. 



Keys 



The X keyboard model is broken into two layers: server- specific codes (called 
keycodes) which represent the physical keys, and server-independent sym- 
bols (called keysyms) which represent the letters or words that appear on the 
keys. Two tables are kept in the server for converting keycodes to keysyms: 

• modifier list 

Some keys (such as SHIFT, CONTROL, and CAPSLOCK) are known 
as modifiers and are used to select different symbols that are attached 
to a single key (such as SHIFT-a generates a capital A, and CONTROL- 
1 generates a formfeed character A L). The server keeps a list of 
keycodes corresponding to the various modifier keys. Whenever a key 
is pressed or released, the server generates an event that contains the 
keycode of the indicated key as well as a mask that specifies which of 
the modifier keys are currently pressed. Most servers set up this list to 
initially contain the various shift, control, and shift lock keys on the 
keyboard. 

• keysym table 

Applications translate event keycodes and modifier masks into 
keysyms using a keysym table which contains one row for each 
keycode and one column for various modifier states. This table is 
initialized by the server to correspond to normal typewriter 
conventions, but is only used by client programs. 
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Although most programs deal with keysyms directly (such as those 
written with the X Toolkit Intrinsics), most programming libraries provide 
routines for converting keysyms into the appropriate type of string (such as 
ISOLatin-1). 

Options 

Most X programs attempt to use the same names for command line options 
and arguments. All applications written with the X Toolkit Intrinsics auto- 
matically accept the following options: 

-display display The name of the X server to use. 

-geometry geometry The initial size and location of the window. 

-bg color, -background color Either option specifies the color to use for 

the window background. 

-bd color, -bordercolor color Either option specifies the color to use for 

the window border. 

-bw number, -borderwidth number 

Either option specifies the width in pixels 
of the window border. 



-fg color, -foreground color 



-f n font, -font font 



-iconic 



-name 



-rv, -reverse 



Either option specifies the color to use for 
text or graphics. 

Either option specifies the font to use for 
displaying text. 

Indicates that the user would prefer the ap- 
plication's windows initially not be visible 
(as if the windows had be immediately ico- 
nified). Window managers may choose not 
to honor the application's request. 

The name under which resources for the ap- 
plication should be found. This option is 
useful in shell aliases to distinguish be- 
tween invocations of an application, with- 
out resorting to creating links to alter the 
executable file name. 

Either option indicates that the program 
should simulate reverse video if possible, 
often by swapping the foreground and 
background colors. Not all programs honor 
this or implement it correctly. It is usually 
only used on monochrome displays. 
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Indicates that the program should not 
simulate reverse video. This is used to 
override any defaults since reverse video 
doesn't always work properly. 

The timeout in milliseconds within which 
two communicating applications must re- 
spond to one another for a selection re- 
quest. 

Indicates that requests to the X server 
should be sent synchronously, instead of 
asynchronously. Since Xlib normally 
buffers requests to the server, errors do not 
necessarily get reported immediately after 
they occur. This option turns off the 
buffering so that the application can be 
debugged. It should never be used with a 
working program. 

The title to be used for this window. This 
information is sometimes used by a win- 
dow manager to provide some sort of head- 
er identifying the window. 



-xnllanguage language[_terrltory][.codeset] 

The language, territory, and code set for use 
in resolving resource and other filenames. 

-xrm A resource name and value to override any 

defaults. It is also very useful for setting 
resources that don't have explicit 
command line arguments. 

To make the tailoring of applications to personal preferences easier, X 
supports several mechanisms for storing default values for program resources 
(e.g., background color, window title, etc.). Resources are specified as strings 
of the form 

appname*subname*subsubname...: value 

that are read in from various places when an application is run. By conven- 
tion, the application name is the same as the program name, but with the first 
letter capitalized (e.g., Bitmap or Emacs) although some programs that be- 
gin with the letter "x" also capitalize the second letter for historical reasons. 
The precise syntax for resources is 
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ResourceLine = Comment | ResourceSpec 

Comment = "!" string | <empty line> 

ResourceSpec = WhiteSpace ResourceName WhiteSpace " : " 
WhiteSpace value 

ResourceName = [Binding] ComponentName {Binding Component- 
Name } 

Binding = "." | "*" 

WhiteSpace = {" " I "\t"} 

ComponentName = {"a"-"z" | "A"-"Z" | »0"-"9" | "_" I "-"} 

value = string 

string = {<any character not including "\n">} 

Note that elements enclosed in curly braces ({...}) indicate zero or more 
occurrences of the enclosed elements 

To allow values to contain arbitrary octets, the 4-character sequence 
\nnn (where n is a digit in the range of 0-7) is recognized and replaced with 
a single byte that contains this sequence interpreted as an octal number. For 
example, a value containing a NULL byte can be stored by specifying \ 0. 

The Xlib routine XGetDefault(3X) and the resource utilities within Xlib 
and the X Toolkit Intrinsics obtain resources from the following sources: 

RESOURCEMANAGER root window property 

Any global resources that should be available to clients on all ma- 
chines should be stored in the RESOURCE_MANAGER property on 
the root window using the xrdb program. This is frequently taken care 
of when the user starts up X through the display manager or xinit. 

application-specific files 

Programs that use the X Toolkit Intrinsics will also look in the 
directories named by the environment variable 
XUSERFILESEARCHPATH or the environment variable 
XAPPLRESDIR, plus directories in a standard place (usually under 
/usr/lib/X11/, but this can be overridden with the 
XFILESEARCHPATH environment variable) for application- specific 
resources . See the X Toolkit Intrinsics - C Language Interface manual 
for details. 

XENVIRONMENT 

Any user- and machine-specific resources may be indicated by set- 
ting the XENVIRONMENT environment variable to the name of a re- 
source file to be loaded by all applications. If this variable is not de- 
fined, a file named $HOME/.Xdefaults-/?osfr?ame is looked for in- 
stead, where hostname is the name of the host where the application 
is executing. 
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-xrm resourcestring 

Applications that use the X Toolkit Intrinsics can have resources spec- 
ified from the command line. The resourcestring is a single resource 
name and value as shown above. Note that if the string contains char- 
acters interpreted by the shell (e.g., asterisk), they must be quoted. 
Any number of -xrm arguments may be given on the command line. 

Program resources are organized into groups called classes so that 
collections of individual resources (each of which are called instances) can be 
set all at once. By convention, the instance name of a resource begins with a 
lowercase letter and class name with an upper case letter. Multiple word 
resources are concatenated with the first letter of the succeeding words 
capitalized. Applications written with the X Toolkit Intrinsics will have at 
least the following resources: 

background (class Background) 

This resource specifies the color to use for the window background. 
borderWidth (class BorderWidth) 

This resource specifies the width in pixels of the window border. 
borderColor (class BorderColor) 

This resource specifies the color to use for the window border. 

Most applications using the X Toolkit Intrinsics also have the resource 
foreground (class Foreground), specifying the color to use for text and 
graphics within the window. 

By combining class and instance specifications, application preferences 
can be set quickly and easily. Users of color displays will frequently want to 
set Background and Foreground classes to particular defaults. Specific 
color instances such as text cursors can then be overridden without having to 
define all of the related resources. For example, 

bitmap*Dashed: off 

XTerm*cursorColor : gold 

XTerm*multiScroll: on 

XTerm* jumpScroll: on 

XTerm*reverseWrap: on 

XTerm*curses : on 

XTerm*Font: 6x10 

XTerm*scrollBar: on 

XTerm*scrollbar*thickness : 5 

XTerm*multiClickTime: 500 

XTerm*charClass: 33 : 48 , 37 : 48 , 45-47 : 48, 64 : 48 

XTerm* cutNewline: off 

XTerm*cutToBeginningOf Line : off 
XTerm*titeInhibit : on 
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XTerm*ttyModes : intr A c erase A ? kill *u # 

XLoad*Background: gold % 

XLoad*Foreground: re 

XLoad*highlight : black 

XLoad*borderWidth: 

emacs*Geometry: 80x65-0-0 

emacs*Background: #5b7 686 

emacs*Foreground: white 

emacs*Cursor: white 

emacs*BorderColor: white 

emacs*Font: 6x10 

xmag*geometry: -0-0 

xmag*borderColor: white 

If these resources were stored in a file called .Xresources in your home 
directory, they could be added to any existing resources in the server with the 
following command: 

% xrdb -merge $HOME/ .Xresources 

This is frequently how user-friendly startup scripts merge user-specific 
defaults into any site-wide defaults. All sites are encouraged to set up 
convenient ways of automatically loading resources. See the Xlib Manual, 
section "Using the Resource Manager," for more information. 

Examples 

The following is a collection of sample command lines for some of the more f 

frequently used commands. For more information on a particular command, I 

please refer to that command's manual page. 

% xrdb -load $HOME/ .Xresources 

% xrnodmap -e "keysym Backspace = Delete" 

% mkfontdir /usr/local/lib/Xll/otherf onts 

% xset fp+ /usr/local/lib/Xll/otherfonts 

% xrnodmap $HOME/ .keymap.km 

% xsetroot -solid '#888' 

% xset b 100 400 c 50 s 1800 r on 

% xset q 

% twm 

% xmag 

% xclock -geometry 48x48-0+0 -bg blue -fg white 

% xeyes -geometry 48x48-48+0 

% xbiff -update 20 

% xlsfonts ' *helvetica*' 

% xlswins -1 

% xwininfo -root 

% xdpyinfo -display joesworkstation: 

% xhost -joesworkstation 

% xrefresh 

% xwd | xwud 

% bitmap company logo. bm 32x32 

% xcalc -bg blue -fg magenta 

•— — ——• ( 
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Diagnostics 

A wide variety of error messages are generated from various programs. 
Various toolkits are encouraged to provide a common mechanism for locating 
error text so that applications can be tailored easily. Programs written to 
interface directly to the Xlib C language library are expected to do their own 
error checking. 

The default error handler in Xlib (also used by many toolkits) uses 
standard resources to construct diagnostic messages when errors occur. The 
defaults for these messages are usually stored in /usr/lib/X11/XErrorDB. If 
this file is not present, error messages will be rather terse and cryptic. 

When the X Toolkit Intrinsics encounter errors converting resource 
strings to the appropriate internal format, no error messages are usually 
printed. This is convenient when it is desirable to have one set of resources 
across a variety of displays (e.g., color vs. monochrome, many fonts vs. very 
few, etc.), although it can pose problems for trying to determine why an 
application might be failing. This behavior can be overridden by the setting 
the StringConversionsWarning resource. 

To force the X Toolkit Intrinsics to always print string conversion error 
messages, the following resource should be placed at the top of the file that 
gets loaded onto the RESOURCE_MANAGER property using the xrdb 
program (frequently called .Xresources or .Xres in your home directory): 

*StringConversionWarnings : on 

To have conversion messages printed for just a particular application, the 
appropriate instance name can be placed before the asterisk: 

xterm*StringConversionWarnings : on 

Bugs 

If you encounter a repeatable bug, please contact your site administrator for 
instructions on how to submit an X Bug Report. 

See Also 

Xlib - C Language X Interface, X Toolkit Intrinsics - C Language Interface, 
and Using and Specifying X Resources 

Copyright 

The following copyright and permission notice outlines the rights and restric- 
tions covering most parts of the core distribution of the X Window System 
from MIT. Other parts have additional or different copyrights and permis- 
sions; see the individual source files. 

Copyright 1984, 1985, 1986, 1987, 1988, and 1989, by the Massachusetts 
Institute of Technology. 
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Permission to use, copy, modify, distribute, and sell this software and its 
documentation for any purpose is hereby granted without fee, provided that 
the above copyright notice appear in all copies and that both that copyright 
notice and this permission notice appear in supporting documentation, and 
that the name of MIT not be used in advertising or publicity pertaining to 
distribution of the software without specific, written prior permission. MIT 
makes no representations about the suitability of this software for any 
purpose. It is provided "as is" without express or implied warranty. 

This software is not subject to any license of the American Telephone and 
Telegraph Company or of the Regents of the University of California. 

UNIX and OPEN LOOK are trademarks of AT&T. X Window System is a 
trademark of MIT. 



Authors 



The X distribution is brought to you by the MIT X Consortium. The staff 
members at MIT responsible for this release are: Donna Converse (MIT X 
Consortium), Jim Fulton (MIT X Consortium), Michelle Leger (MIT X Con- 
sortium), Keith Packard (MIT X Consortium), Chris Peterson (MIT X Con- 
sortium), Bob Scheifler (MIT X Consortium), and Ralph Swick (Digital/MIT 
Project Athena). 
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Name 

Xesv - X Version 1 1 server for Evans and Sutherland ES V Workstation 

Syntax 

Xesv [ -keyboard kbd-dev][ -mouse mouse-dev\ 
[ -dials dials-dev\[ -tablet tablet-dev] 
[ -mouseptr mouse-dev][ -tabletptr tablet-dev] 
[ -nscreens NxM] [ -stereoscr screen-numbed 
[ -stereotallscr screen-numbei] 
[ -tc32scr screen-numbei] 
[ -dc32scr screen-numbei] 
[ -pc8scr screen-numbei] 

Description 

Xesv is the server for Version 1 1 of the X Window System on an Evans & 
Sutherland ES V Workstation. It is normally started using startesvx, xdm(1 ), 
orxlnlt(1). 

In addition to the standard X Version 1 1 Revision 4 protocol, Xesv also 
supports the following extensions: 

• PEX (PHIGS Extension to X), 

• X Input Extension, 

• X Picking Extension, and 

• Non-Rectangular Window Shape Extension. 

The ES V Workstation has a double-buffered 24-plane RGB frame buffer 
with z-buffered hidden line and hidden surface removal (HLHSR). 

Options 

-keyboard kbd-dev The device to be used as the X core keyboard. De- 
fault is /dev/kbd. 

-mouse mouse-dev The input extension device to be used as a mouse. 

-dials dials-dev Specifies an alternative input extension device to 

be used as an 8-dial knob box. Default is 
/dev/dials. 

-tablet tablet-dev The input extension device to be used as a data tab- 

let. Default is /dev/tablet. 

-mouseptr mouse-dev The input extension device to be used as mouse 
and use it as the X core pointer. Default is /dev/ 
mouse. 
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-tablet ptr tablet-dev The input extension device to be used as a data tab- 
let and use it as the X core pointer. 

-nscreens MxN Creates multiple screens conceptually arrayed in M 

rows and W columns. 

-stereoscr screen-number 

Makes the screen specified by screen-number a. 
screen with stereo video format. It will be 640x5 12 
pixels, half the resolution of the standard screen. 

-stereotallscr screen-number 

Makes the screen specified by screen-number a. 
screen with "tall" stereo video format. It will be 
1280x512 pixels, half the resolution of the stan- 
dard screen in the vertical direction, and full reso- 
lution in the horizontal direction. 

-tc32scr screen-number 

Causes the root window on the screen specified by 
screen-number to have a visual of class 
TrueColor and a depth of 32. This is the default. 
Note that some clients which assume the root 
window is of class PseudoColor or DirectColor 
will probably not work on a TrueColor root 
window. 

-dc32scr screen-number 

Causes the root window on the screen specified by 
screen-number to have a visual class of Direct- 
Color and depth of 32. 

-pc8scr screen-number 

Causes the root window on the screen specified by 
screen-number to have a visual class of 
PseudoColor and a depth of 8. 

Environment 

X__IPC If this environment variable is set, Xesv will use its 

value to specify the program which is called to cre- 
ate the shared memory segment for graphics struc- 
ture memory and to create the interprocess 
communication semaphores. Defaults to 
/usr/bin/X11/esvipc. 
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PEX CONFIG 



GM CONFIG 



GM TMPDIR 



ISO PHIGS 



Files 

pex_config.dat 



gm_config.dat 



If this environment variable is set, Xesv will use its 
value to specify the program to load the graphics 
subsystem microcode. Defaults to 
/usr/bin/X11/dspstart. 

If this environment variable is set, Xesv will use its 
value to specify the PEX configuration file. This 
file determines the maximum number of entries in 
the various workstation tables among other things. 
Defaults to /usr/lib/X1 1Zpex_config.dat. 

If this environment variable is set, Xesv will use its 
value to specify the graphics manager configura- 
tion file. This file determines the maximum size of 
the shared memory segment for graphics structure 
memory among other things. Defaults to 
/usr/lib/X1 1/gm_config.dat. 

If this environment variable is set, Xesv will use its 
value to specify the directory in which to create the 
graphics manager error log file in the unfortunate 
event that graphics manager errors occur. Defaults 
to/tmp. 

If this environment variable is set, visual priority is 
guaranteed for posted structures. However, you 
may experience performance degradation if multi- 
ple structures are posted to a single workstation. 



This file is used to specify the maximum size and 
the number of predefined entries in PHIGS work- 
station tables. If the environment variable 
PEX_CONFIGis set, its value will be used to spec- 
ify the full pathname of the file to be used for the 
PEX configuration file. Normally, pex_config.dat 
is found in the /usr/lib/X1 1 directory. 

This file is used to specify sizes of graphics man- 
ager internal objects as well as the default RGB 
color lookup table. If the environment variable 
GM_CONFIGis set, its value will be used to spec- 
ify the full pathname of the file to be used for the 
graphics manager configuration file. Normally, 
dm_config.dat is found in the /usr/lib/X11 direc- 
tory. 
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Xjgmerrlog This file is generated by Xesv if the graphics man- 

ager encounters errors. The error description will 
be left in this file. If the environment variable 
GMJTMPDIR'n set, its value will be used to spec- 
ify the directory in which to place Xjgmerrlog. 

/tmpsminfo This file is used to communicate the identification 

information of the shared memory segment for 
structure memory and the interprocess communi- 
cation semaphores. 

Examples 

The -tc32scr, -dc32scr, and -pcSscr options assist with binary compatibility 
of existing X applications. Since many X servers to date have only supported 
visuals of depth 8 and class PseudoColor, numerous applications were written 
assuming this as a default visual type for all servers. Such applications will 
not work with a server whose depth is 32 and class is TrueColor. If an existing 
application fails, try restarting the server with the -pc8scr option and run the 
application again. 

With the multiple screen option, many screens can be started each with a 
different depth. You could, for example, start the server with the following 
options 

-nscreens 3 -dc32scr 1 -pc8scr 2 
This results in three screens: screen is TrueColor, screen 1 is DirectColor, 
and screen 2 is PseudoColor. 

See Also 

Xserver(1), X(1), xdm(1), xlnit(1), esvipc(1), gm_config(5), 
pex_config(5), ESV Workstation User's Manual 

Diagnostics 

Too numerous to list, but all self-explanatory. 
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xcm 



Name 

xcm - X Client Manager for easy access to X and PEX Clients on the ESV. 
Syntax 

xcm 

Description 

The xcm client provides users with the ability to access X clients via a menu 
system. 

The xcm menu system is configurable by making changes to the .xcmrc 
file in the users home directory. If this file doesn't exist then the file 
/usr/lib/X1 1 /system.xcmrc is accessed for menu configuration information. 
The format of the .xcmrc file is: 

Menu 

{menu number} 

{client program path and name} 
{client program path and name} 



There are 4 menu bar selections that can be specified, XGames (Menul), 
XClients (Menu2), PexClients (Menu3) andESVDemos (Menu4). Most any 
executable program may be entered as menu items. Command line arguments 
can be included in the .xcmrc file as they would appear if typed at the shell 
prompt. 

These clients are run in the background and should be managed as such. 

Options 

xcm is written using the Motif Widget Set and it accepts the typical command 
line options parsed by toolkit clients. 

Usage 

xcm 

Bugs 

None known at this time. 
Copyright 

Copyright 1991, Evans & Sutherland Computer Corporation. 
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csm 



Name 

csm - Multiscreen manager for X servers supporting multiple screens 
Syntax 

csm 

Description 

The csm client allows users to switch between screens on an ES V 
workstation, csm displays a matrix of buttons and small text areas, each 
button corresponding to an available screen in the running X Server. The 
button that corresponds to the screen being displayed is highlighted in a 
different color. Clicking on a button causes the associated screen to be 
displayed on the monitor. 

In addition, small text "note pads" are found to the right of each numbered 
button. The note pads can be used to type labels or reminders indicating the 
use of each screen. 

When csm first starts, it displays special messages in the note pad areas 
to identify screens that have special characteristics. Stereo screens are marked 
"-Stereo." Screens whose root windows have a pseudo-color visual type are 
marked "-Pseudo." Screens whose root windows have a direct-color visual 
type are marked "-Direct." Screens whose root windows have a true-color vi- 
sual type are not marked (true-color is the default). 

Options 

csm is written using the Motif toolkit and it accepts the typical command line 
options parsed by toolkit clients. 

Keyboard Support 

When the cursor is within the borders of csm, the tab key may be used to 
move focus from one button or text note pad to the next. If focus is on one of 
the numbered buttons, the ENTER key may be used to warp (switch) to the 
screen associated with the button. 

Resources 

The csm client pays attention to the standard resources used by Motif and the 
mwm window manager, csm also pays attention to the following specific 
resources: 

font List The font to use in creating csm's buttons 

and text. Applies only to non-stereo 
screens. Use stereoFont List for setting the 
font for stereo screens. 
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hlButtonColor 



margin Width 



marginHelght 



notePadWidth 



spacing 



stereoFontList 
stereoNotePadWidth 
stereoMargin Width 
stereoMarginHeight 



The numbered button that corresponds to 
the screen being displayed is highlighted by 
csm. This resource allows the user to cus- 
tomize the color of the button. 

The size of the horizontal margin between 
csm's border and csm's button and text 
widgets. Applies to non-stereo screens. Use 
stereoMarginWidth for setting the margin 
width on stereo screens. 

The size of the vertical margin between 
csm's border and csm's button and text 
widgets. Applies to non-stereo screens. Use 
stereoMargin Height for setting the margin 
height on stereo screens. 

Next to each numbered button there is a 
small text widget that allows users to type 
anything that they wish as a note to 
themselves about what is on each screen. 
This resource sets the size of the text widget 
in the number of characters. It only applies 
to non- stereo screens. Use 
StereoNotePadWidth for setting the note 
pad size on stereo screens. 

The horizontal and vertical spacing be- 
tween buttons and text used by csm in pix- 
els. Applies only to non-stereo screens. Use 
stereoSpacing for setting csm button 
spacing on stereo screens. 

The same as the fontList resource except it 
applies to stereo and tall stereo screens 
only. 

The same as the notePadWidth resource 
except it applies to stereo and tall stereo 
screens only. 

The same as the margin Width resource 
except it applies to stereo and tall stereo 
screens only. 

The same as the marginHeight resource 
except it applies to stereo and tall stereo 
screens only. 
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stereoSpaclng The same as the spacing resource except it f 

applies to stereo and tall stereo screens V 

only. 

Example .Xdefaults 

In particular, here is an example of customizing resources for csm in your 
.Xdefaults file: 

csm* font Li st : -adobe-new century schoolbook-*-*-*-*-14-*-*-*-*-*-*-* 

csm*marginWidth: 3 

csm*marginHeight : 3 

csm* spacing: 3 

csm.notePadWidth: 15 

csm*stereoFontList : _*_*_b i c i_ r _*_*--i:L_*_*--*--*_*_*_* 

csm*stereoMarginWidth: 

csm*stereoMarginHeight : 

csm*stereoSpacing: 

csm.stereoNotePadWidth: 8 

csm. geometry : +5+5 

csm.hiButtonColor : deeppink 

Bugs 

None known at this writing. 
Copyright |^ 

Copyright 1990, Evans and Sutherland Computer Corporation. 



C 



3 - 26 ESV Workstation Reference Manual [2.0] 



X Clients 



mwm 



Name 

mwm - A Window Manager 

Syntax 

mwm [options] 

Description 

mwm is an XI 1 client that provides window management functionality and 
some session management functionality. It provides functions that facilitate 
control (by the user and the programmer) of elements of window states such 
as placement, size, icon/normal display, input focus ownership, etc. It also 
provides session management functions such as stopping a client. 

Options 

-display display The display to use; see X(1 ). 

xrm resourcestring A resource string to use. 

Appearance 

The following sections describe the basic default behaviors of windows, 
icons, the icon box, input focus, and window stacking. The appearance and 
behavior of the window manager can be altered by changing the configuration 
of specific resources. Resources are defined under the heading "X Defaults." 

Windows 

Default mwm window frames have distinct components with associated 
functions: 

Title Area In addition to displaying the client's title, the title 

area is used to move the window. To move the 
window, place the pointer over the title area, press 
button 1 and drag the window to a new location. A 
wire frame is moved during the drag to indicate the 
new location. When the button is released, the 
window is moved to the new location. 

Title Bar This includes the title area, the minimize button, the 

maximize button and the window menu button. 

Minimize Button To turn the window back into its icon, do a button 1 

click on the minimize button (the frame box with a 
small square in it). 

Maximize Button To make the window fill the screen (or enlarge to the 

largest size allowed by the configuration files), do a 
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button 1 click on the maximize button (the frame box 
with a large square in it). 

Window Menu Button The window menu button is the frame box with a 
horizontal bar in it. To pop up the window menu, 
press button 1. While pressing, drag the pointer on 
the menu to your selection, then release the button 
when your selection is highlighted. Alternately, you 
can click button 1 to pop up the menu and keep it 
posted; then position the pointer and select. 



Resize Border Handles 



Matte 



Icons 



To change the size of a window, move the pointer 
over a resize border handle (the cursor will change), 
press button 1, and drag the window to a new size. 
When the button is released, the window is resized. 
While dragging is being done, a rubber-band oudine 
is displayed to indicate the new window size. 

An optional matte decoration can be added between 
the client area and the window frame. A matte is not 
actually part of the window frame. There is no func- 
tionality associated with a matte. 



Icons are small graphic representations of windows. A window can be mini- 
mized (iconified) using the minimize button on the window frame. Icons pro- 
vide a way to reduce clutter on the screen. 

Pressing mouse button 1 when the pointer is over an icon will cause the 
icon's window menu to pop up. Releasing the button (press + release without 
moving mouse = click) will cause the menu to stay posted. The menu contains 
the following selections: 

Icon Window Menu 

Description 

Opens the associated window. 
Allows the icon to be moved with keys. 
Inactive (not an option for icons). 
Inactive (not an option for icons). 
Opens the associated window and makes 
it fill the screen. 

Moves icon to bottom of icon stack. 
Removes client from mwm management. 



Selection 


Accelerator 


Restore 


ALT+F5 


Move 


ALT+F7 


Size 


ALT+F8 


Minimize 


ALT+F9 


Maximize 


ALT+F10 


Lower 


ALT+F11 


Close 


ALT+F4 



( 



( 
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Double-clicking button 1 on an icon normalizes the icon into its 
associated window. Double-clicking button 1 on the icon box's icon opens 
the icon box and allow access to the contained icons. (In general, double- 
clicking a mouse button offers a quick way to have a function performed. 
Another example is double-clicking button 1 with the pointer on the window 
menu button. This closes the window.) 

Icon Box 

When icons begin to clutter the screen, they can be packed into an icon box. 
(To use an icon box, mwm must be started with the icon box configuration 
already set.) The icon box is a window manager window that holds client 
icons. Icons in the icon box can be manipulated with the mouse. The follow- 
ing table summarizes the behavior of this interface. Button actions apply 
whenever the pointer is on any part of the icon. 

Button Action Description 

Button 1 click Selects the icon. 

Button 1 double click Normalizes (opens) the associated win- 
dow. 
Button 1 double click Raises an already open window to the top 

of the stack. 
Button 1 drag Moves the icon. 

The window menu of the icon box differs from the window menu of a 
client window. The "Close" selection is replaced with the "Packlcons 
ALT+F12" selection. When selected, Packlcons packs the icons in the box to 
achieve neat rows with no empty slots. 

Input Focus 

mwm supports (by default) a keyboard input focus policy of explicit selec- 
tion. This means when a window is selected to get keyboard input, it contin- 
ues to get keyboard input until the window is withdrawn from window man- 
agement, another window is explicitly selected to get keyboard input, or the 
window is iconified. There are numerous resources that control the input fo- 
cus. The client window with the keyboard input focus has the active window 
appearance with a visually distinctive window frame. 

These tables summarize the keyboard input focus selection behavior: 

Button Action Object Function Description 

Button 1 press Window/window frame Keyboard focus selection 
Button 1 press Icon Keyboard focus selection 

Key Action Function Description 

[ALT] [TAB] Move input focus to next window in window stack. 

[ALT] [SHIFT] [TAB] Move input focus to previous window in stack. 
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Window Stacking 

The stacking order of windpws may be changed as a result of setting the key- 
board input focus, iconifying a window, or by doing a window manager win- 
dow stacking function. When a window is iconified, the window's icon is 
placed on the bottom of the stack. 

The following table summarizes the default window stacking behavior of 
the window manager: 

Key Action Function Description 

[ALT] [ESC] Put bottom window on top of stack. 

[ALT] [SHIFT] [ESC] Put top window on bottom of stack. 

A window can also be raised to the top when it gets the keyboard input 
focus (e.g., by doing a button 1 press on the window or by using [ALT] [TAB]) 
if this auto-raise feature is enabled with the focus Auto Raise resource. 

X Defaults 

mwm is configured from its resource database. This database is built from the 
following sources. They are listed in order of precedence, low to high: 

app-defaults/Mwm 

RESOURCE MANAGER root window property or 
$HOME/.Xdefaults 

• XENVIRONMENT variable or $HOME/.Xdefaults-host 

• mwm command line options 

Entries in the resource database may refer to other resource files for 
specific types of resources. These include files that contain bitmaps, fonts, 
and mwm specific resources such as menus and behavior specifications (i.e., 
button and key bindings). 

Mwm is the resource class name of mwm, and mwm is the resource name 
used by mwm to look up resources. In the following discussion of resource 
specification Mwm and mwm can be used interchangeably. 

mwm uses the following types of resources: 

Component Appearance Resources: These resources specify 
appearance attributes of window manager user interface components. They 
can be applied to the appearance of window manager menus, feedback 
windows (e.g., the window reconfiguration feedback window), client window 
frames, and icons. 

Appearance and Behavior Resources: These resources specify mwm 
appearance and behavior (e.g., window management policies). They are not 
set separately for different mwm user interface components. 
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Client Specific Resources: These mwm resources can be set for a 

particular client window or class of client windows. They specify client- 
specific icon and client window frame appearance and behavior. 

Resource identifiers can be either a resource name (e.g., foreground) or 
a resource class (e.g., Foreground). If the value of a resource is a filename 
and if the filename is prefixed by -/, then it is relative to the path contained 
in the $HOME environment variable (generally the user's home directory). 
This is the only environment variable mwm uses directly 
($XENVIRONMENT is used by the resource manager). 

• Specifying Component Appearance Resources 

The syntax for specifying component appearance resources that apply to 
window manager icons, menus, and client window frames is 

Mwm'resourcejd 

For example, Mwm * foreground is used to specify the foreground color 
for mwm menus, icons, and client window frames. 

The syntax for specifying component appearance resources that apply to 
a particular mwm component is 

Mwm*[menu|!con|client|feedback]*resource_/cf 

If menu is specified, the resource is applied only to mwm menus; if icon 
is specified, the resource is applied to icons; and if client is specified, the 
resource is applied to client window frames. For example, 
Mwm*\con* foreground is used to specify the foreground color for mwm 
icons, Mwm*menu* foreground specifies the foreground color for mwm 
menus, and Mvim*c\\en\* foreground is used to specify the foreground color 
for mwm client window frames. 

The appearance of the title area of a client window frame (including 
window management buttons) can be separately configured. The syntax for 
configuring the title area of a client window frame is: 

Mwm*client*title* resourcejd 

For example, Mwm*client*title*foreground specifies the foreground 
color for the title area. Defaults for title area resources are based on the values 
of the corresponding client window frame resources. 

The appearance of menus can be configured based on the name of the 
menu. The syntax for specifying menu appearance by name is: 

Mvim*menu*menu_name*resource_id 

For example, Mwm*menu*my_menu*foregfrouncf specifies the 
foreground color for the menu named my_menu. 

The following component appearance resources that apply to all window 
manager parts can be specified: 
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Component Appearance Resources - All Window Manager Parts 



Name 



Class 



Default 



background 

backgroundPixmap 

bottomShadowColor 

bottomShadowPixmap 

fontLSst 

foreground 

saveUnder 

topShadowColor 

topShadowPlxmap 



vanes* 

varies* 

varies* 

varies* 

fixed 

varies* 

F 

varies* 

varies* 



Value Type 

Background color 

BackgroundPixmap string** 

Foreground color 
BottomShadowPixmap string** 

FontList string*** 

Foreground color 

SaveUnder T/F 

Background color 

TopShadowPlxmap string** 

*The default is chosen based on the visual type of the screen. 
**Pixmap image name. See Xmlnstalllmage(3X). 
***X1 1 R3 Font description. 

background (class Background) 

This resource specifies the background color. Any legal X color may be 
specified. The default value is chosen based on the visual type of the screen. 

backgroundPixmap (class BackgroundPixmap) 

This resource specifies the background Pixmap of the mwm decoration 
when the window is inactive (does not have the keyboard focus). The default 
value is chosen based on the visual type of the screen. 

bottomShadowCoior (class Foreground) 

This resource specifies the bottom shadow color. This color is used for the 
lower and right bevels of the window manager decoration. Any legal X color 
may be specified. The default value is chosen based on the visual type of the 
screen. 

bottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap. This Pixmap is used 
for the lower and right bevels of the window manager decoration. The default 
is chosen based on the visual type of the screen. 

fontList (class Font) 

This resource specifies the font used in the window manager decoration. 
The character encoding of the font should match the character encoding of the 
strings that are used. The default is "fixed." 

foreground (class Foreground) 

This resource specifies the foreground color. The default is chosen based 
on the visual type of the screen. 



( 
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saveUnder (class BaveUnder) 

This is used to indicate whether "save unders" are used for mwm 
components. For this to have any effect, save unders must be implemented by 
the X server. If save unders are implemented, the X server will save the 
contents of windows obscured by windows that have the save under attribute 
set. If the saveUnder resource is true, mwm will set the save under attribute 
on the window manager frame of any client that has it set. If saveUnder is 
false, save unders will not be used on any window manager frames. The 
default value is false. 

topShadowColor (class Background) 

This resource specifies the top shadow color. This color is used for the 
upper and left bevels of the window manager decoration. The default is 
chosen based on the visual type of the screen. 

topShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap. This Pixmap is used for 
the upper and left bevels of the window manager decoration. The default is 
chosen based on the visual type of the screen. 

The following component appearance resources that apply to frame and 
icons can be specified: 

Frame and Icon Components 

Name 

activeBackground 

activeBackgroundPlxmap 

activeBottomShadowColor 

activeBottomShadowPlxmap 

activeForeground 

activeTopShadowCotor 

activeTopShadowPixmap 

*The default is chosen based on the visual type of the screen. 
**See Xmlnstalllmage(3X). 

activeBackground (class Background) 

This resource specifies the background color of the mwm decoration 
when the window is active (has the keyboard focus). The default is chosen 
based on the visual type of the screen. 

activeBackgroundPlxmap (class ActiveBackgroundPlxmap) 

This resource specifies the background Pixmap of the mwm decoration 
when the window is active (has the keyboard focus). The default is chosen 
based on the visual type of the screen. 
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Default 


Background color 


varies* 


BackgroundPixmap string* * 


varies* 


Foreground color 


varies* 


BottomShadowPixmap string** 


varies* 


Foreground color 


varies* 


Background color 


varies* 


TopShadowPixmap string** 


varies* 
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activeBottomShadowColor (class Foreground) f~ 

This resource specifies the bottom shadow color of the mwm decoration 
when the window is active (has the keyboard focus). The default is chosen 
based on the visual type of the screen. 

activeBottomShadowPlxmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the mwm 
decoration when the window is active (has the keyboard focus). The default 
is chosen based on the visual type of the screen. 

activeForeground (class Foreground) 

This resource specifies the foreground color of the mwm decoration when 
the window is active (has the keyboard focus). The default is chosen based on 
the visual type of the screen. 

activeTopShadowColor (class Background) 

This resource specifies the top shadow color of the mwm decoration 
when the window is active (has the keyboard focus). The default is chosen 
based on the visual type of the screen. 

activeTopShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the mwm decoration 
when the window is active (has the keyboard focus). The default is chosen 
based on the visual type of the screen. 

• Specifying Appearance and Behavior Resources 

The syntax for specifying appearance and behavior resources is 

Uvtm*resourceJd 

For example, Mwm k key boat dFocusPoiscy specifies the window 
manager policy for setting the keyboard focus to a particular client window. 
The following appearance and behavior resources can be specified: 
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Specific Appearance and Behavior Resources 


Name 


Class Value Type 


Default 


autoKeyFocus 


AutoKeyFocus 


T/F 


T 


autoRaiseDelay 


AutoRaiseDelay 


millisec 


500 


bitmapDlrectory 


BltmapDirectory 


directory 


/usr/include/X1 1 /bitmaps 


buttonBindings 


ButtonBindings 


string 


NULL 


cleanText 


CleanText 


T/F 


T 


clientAutoPlace 


ClientAutoPlace 


T/F 


T 


colormapFocusPolicy 


ColormapFocusPolicy 


string 


keyboard 


configFile 


ConfigFile 


file 


.mwmrc 


deiconifyKeyFocus 


DeiconifyKeyFocus 


T/F 


T 


doubleCUckTime 


DoubleCUckTime 


millisec. 


500 


enforceKeyFocus 


EnforceKeyFocus 


T/F 


T 


fadeNormalBcon 


FadeNormallcon 


T/F 


F 


frameBorderWidth 


FrameBorderWidth 


pixels 


5 


iconAutoPlace 


IconAutoPlace 


T/F 


T 


IconBoxGeometry 


IconBoxGeometry 


string 


6x1+0-0 


icon Box Name 


IconBoxName 


string 


iconbox 


IconBoxTitle 


IconBoxTitle 


string 


Icons 


IconClick 


IconClick 


T/F 


T 


iconDecoration 


IconDecoration 


string 


varies 


iconlmageMaximum 


IconlmageMaximum 


wxh 


50x50 


IconlmageMinimum 


IconlmageMinimum 


wxh 


32x32 


iconPlacement 


IconPlacement 


string 


left bottom 


IconPlacementMargin 


IconPlacementMargln 


pixels 


varies 


InteractivePlacement 


InteractivePlacement 


T/F 


F 


keyBindings 


KeyBindings 


string 


system 


keyboardFocusPollcy 


KeyboardFocusPollcy 


string 


explicit 


UmitResize 


UmitResize 


T/F 


T 


lowerOnlconify 


LowerOnlconify 


T/F 


T 


maximumMaximumSize 


MaximumMaximumSize 


wxh(pixels) 2Xscreenw&h 


moveThreshold 


MoveThreshold 


pixels 


4 


passButtons 


PassButtons 


T/F 


F 


passSelectButton 


PassSelectButton 


T/F 


T 


posltionlsFrame 


PosltionlsFrame 


T/F 


T 


positionOnScreen 


PositionOnScreen 


T/F 


T 


quitTimeout 


QuitTimeout 


millisec. 


1000 


resizeBorderWidth 


ResizeBorderWidth 


pixels 


10 


resizeCursors 


ResizeCursors 


T/F 


T 


showFeedback 


ShowFeedback 


string 


all 


startupKeyFocus 


StartupKeyFocus 


T/F 


T 


transientDecoration 


TransientDecoration 


string 


system title 


transientFunctions 


TransientFunctions 


string 


-minimize -maximize 


uselconBox 


UselconBox 


T/F 


F 


wMenuButtonClick 


WMenuButtonClick 


T/F 


T 


wMenuButtonClick2 


WMenu Button CI ick2 


T/F 


T 
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autoKeyFocus (class AutoKeyFocus) 

This resource is only available when the keyboard input focus policy is 
explicit. If autoKeyFocus is given a value of true, then when a window with 
the keyboard input focus is withdrawn from window management or is 
iconified, the focus is set to the previous window that had the focus. If the 
value given is false, there is no automatic setting of the keyboard input focus. 
The default value is true. 

autoRaiseDelay (class AutoRaiseDelay) 

This resource is only available when the focusA utoRaise resource is true 
and the keyboard focus policy is pointer. The autoRaiseDelay resource 
specifies the amount of time (in milliseconds) that mwm will wait before 
raising a window after it gets the keyboard focus. The default value of this 
resource is 500 ms. 

bitmapDirectory (class BitmapDirectory) 

This resource identifies a directory to be searched for bitmaps referenced 
by mwm resources. This directory is searched if a bitmap is specified without 
an absolute pathname. The default value for this resource is 
/usr/include/X1 1 /bitmaps. 

buttonBindings (class ButtonBindings) 

This resource identifies the set of button bindings for window 
management functions. The named set of button bindings is specified in the 
mwm resource description file. These button bindings are merged with the 
built-in default bindings. The default value for this resource is NULL (i.e., no 
button bindings are added to the built-in button bindings). 

cleanText (class CleanTexf) 

This resource controls the display of window manager text in the client 
title and feedback windows. If the default value of true is used, the text is 
drawn with a clear (no stipple) background. This makes text easier to read on 
monochrome systems where a background Pixmap is specified. Only the 
stippling in the area immediately around the text is cleared. If false, the text 
is drawn directly on top of the existing background. 

clientAutoPlace (class ClientAutoPlace) 

This resource determines the position of a window when the window has 
not been given a user specified position. With a value of true, windows are 
positioned with the top left comers of the frames offset horizontally and 
vertically. A value of false causes the currendy configured position of the 
window to be used. In either case, mwm will attempt to place the windows 
totally on-screen. The default value is true. 



( 



( 
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colormapFocusPollcy (class ColormapFocusPolicy) 

This resource indicates the colormap focus policy that is to be used. If the 
resource value is explicit then a colormap selection action is done on a client 
window to set the colormap focus to that window. If the value is pointer then 
the client window containing the pointer has the colormap focus. If the value 
is keyboard then the client window that has the keyboard input focus will 
have the colormap focus. The default value for this resource is keyboard. 

configFile (class ConfigFUe) 

The resource value is the pathname for an mwm resource description file. 
The default is .mwmrc in the user's home directory (based on the $HOME 
environment variable) if this file exists, otherwise it is 
/usr/lib/X1 1/system.mwmrc. 

deiconifyKeyFocus (class DeiconifyKeyFocus) 

This resource only applies when the keyboard input focus policy is 
explicit. If a value of true is used, a window will receive the keyboard input 
focus when it is normalized (not iconified). True is the default value. 

doubledickTime (class DoubleClickTime) 

This resource is used to set the maximum time (in ms) between the clicks 
(button presses) that make up a double-click. The default value of this 
resource is 500 ms. 

enforceKeyFocus (class EnforceKeyFocus) 

If this resource is given a value of true, then the keyboard input focus is 
always explicitly set to selected windows even if there is an indication that 
they are "globally active" input windows. (An example of a globally active 
window is a scroll bar that can be operated without setting the focus to that 
client.) If the resource is false, the keyboard input focus is not explicitly set 
to globally active windows. The default value is true. 

fadeNormallcon (class FadeNormallcori) 

If this resource is given a value of true, an icon is grayed out whenever it 
has been normalized (its window has been opened). The default value is false. 

frameBorderWidih (class FrameBorderWidth) 

This resource specifies the width (in pixels) of a client window frame 
border without resize handles. The border width includes the 3-D shadows. 
The default value is 5 pixels. 

iconAutoPlace (class IconAutoPlace) 

This resource indicates whether icons are automatically placed on the 
screen by mwm, or are placed by the user. Users may specify an initial icon 
position and may move icons after initial placement; however, mwm will 
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adjust the user-specified position to fit into an invisible grid. When icons are 
automatically placed, mwm places them into the grid using a scheme set with 
the iconPlacement resource. If the IconAutoPlace resource has a value of 
true, then mwm does automatic icon placement. A value of false allows user 
placement. The default value of this resource is true. 

iconBoxGeometry (class IconBoxGeometry) 

This resource indicates the initial position and size of the icon box. The 
value of the resource is a standard window geometry string with the following 
syntax: 

[=] [widthxheight] [ {+-}xof f set {+-}yof f set] 

If the offsets are not provided, the IconPlacement policy is used to 
determine the initial placement. The units for width and height are columns 
and rows. 

The actual screen size of the icon box window will depend on the 
iconlmageMaximum (size) and IconDecoration resources. The default 
value for size is (6 * iconWidth + padding) wide by (1 * iconlleight + 
padding) high. The default value of the location is +0 -0. 

IconBoxName (class IconBoxName) 

This resource specifies the name that is used to look up icon box 
resources. The default name is "iconbox." 

iconBoxTitle (class IconBoxTltle) 

This resource specifies the name that is used in the title area of the icon 
box frame. The default value is "Icons." 

iconCUck (class IconClick) 

When this resource is given the value of true, the system menu is posted 
and left posted when an icon is clicked. The default value is true. 

IconDecoration (class IconDecoration) 

This resource specifies the general icon decoration. The resource value is 
label (only the label part is displayed) or image (only the image part is 
displayed) or label Image (both the label and image parts are displayed). A 
value of acflvelabel can also be specified to get a label (not truncated to the 
width of the icon) when the icon is selected. The default decoration for icon 
box icons is each one has a label part and an image part (label image). The 
default icon decoration for stand-alone icons is each one has an active label 
part, a label part and an image part (activelabel label image). 

iconlmageMaximum (class IconlmageMaximum) 

This resource specifies the maximum size of the icon image. The resource 
value is widthxheight (e.g., 64x64). The maximum supported size is 
128x128. The default value of this resource is 50x50. 
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IconlmageMinimum (class IconlmageMinimum) 

This resource specifies the minimum size of the icon image. The resource 
value is wldthxhelght(e.g., 32x50). The minimum supported size is 16x16. 
The default value of this resource is 32x32. 

IconPlacement (class IconPlacemenf) 

This resource specifies the icon placement scheme to be used. The 
resource value has the following syntax: 

prlmaryjayout secondaryjayout 
The layout values are one of the following: 

top Lay the icons out top to bottom. 

bottom Lay the icons out bottom to top. 
left Lay the icons out left to right. 

right Lay the icons out right to left. 

A horizontal (or vertical) layout value should not be used for both the 
prlmaryjayout and the secondaryjayout (e.g., don't use top for the 
prlmaryjayout and bottom for the secondaryjayout). The 
prlmaryjayo ut indicates whether, when an icon placement is done, the icon 
is placed in a row or a column and the direction of placement. The 
secondaryjayout indicates where to place new rows or columns. For 
example, top right indicates that icons should be placed top to bottom on the 
screen and that columns should be added from right to left on the screen. The 
default placement is left bottom (icons are placed left to right on the screen, 
with the first row on the bottom of the screen, and new rows added from the 
bottom of the screen to the top of the screen). 

IconPlacementMargin (class IconPlacementMargin) 

This resource sets the distance between the edge of the screen and the 
icons that are placed along the edge of the screen. The value should be greater 
than or equal to 0. A default value (see below) is used if the value specified 
is invalid. The default value for this resource is equal to the space between 
icons as they are placed on the screen. (This space is based on maximizing the 
number of icons in each row and column.) 

interactivePlacement (class InteractivePlacemenf) 

This resource controls the initial placement of new windows on the 
screen. If the value is true, then the pointer shape changes before a new 
window is placed on the screen to indicate to the user that a position should 
be selected for the upper-left hand corner of the window. If the value is false, 
then windows are placed according to the initial window configuration 
attributes. The default value of this resource is false. 
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keyBlndlngs (class Key Bindings) 

This resource identifies the set of key bindings for window management 
functions. If specified these key bindings replace the built-in default bindings. 
The named set of key bindings is specified in mwm resource description file. 
The default value is the set of system-compatible key bindings. 

keyboardFocusPollcy (class KeyboardFocusPolicy) 

If set to pointer, the keyboard focus policy is to have the keyboard focus 
set to the client window that contains the pointer (the pointer could also be in 
the client window decoration that mwm adds). If set to explicit, the policy is 
to have the keyboard focus set to a client window when the user presses 
button 1 with the pointer on the client window or any part of the associated 
mwm decoration. The default value for this resource is explicit. 

UmitResize (class LimitResize) 

If this resource is true, the user is not allowed to resize a window to greater 
than the maximum size. The default value for this resource is true. 

lowerOnlconify (class LowerOnlconify) 

If this resource is given the default value of true, a window's icon appears 
on the bottom of the window stack when the window is minimized 
(iconified). A value of false places the icon in the stacking order at the same 
place as its associated window. 

maximumMaxImumStze (class MaxlmumMaximumSize) 

This resource is used to limit the maximum size of a client window as set 
by the user or client. The resource value is widthxheight (e.g., 1024x1024) 
where the width and height are in pixels. The default value of this resource is 
twice the screen width and height. 

moveThreshold (class MoveThreshold) 

This resource is used to control the sensitivity of dragging operations that 
move windows and icons. The value of this resource is the number of pixels 
that the locator will be moved with a button down before the move operation 
is initiated. This is used to prevent window/icon movement when a click or 
double-click is done and there is unintentional pointer movement with the 
button down. The default value of this resource is 4 pixels. 

passButtons (class PassButtons) 

This resource indicates whether or not button press events are passed to 
clients after they are used to do a window manager function in the client 
context. If the resource value is false, then the button press will not be passed 
to the client. If the value is true, the button press is passed to the client 
window. The window manager function is done in either case. The default 
value for this resource is false. 



3 - 40 ESV Workstation Reference Manual [2.0] 



c 



c 



X Clients 



passSeiectButton (class PassSelectButiori) 

This resource indicates whether or not the keyboard input focus selection 
button press (if key board Foe usFo! icy is explicit) is passed on to the client 
window or used to do a window management action associated with the 
window decorations. If the resource value is false then the button press will 
not be used for any operation other than selecting the window to be the 
keyboard input focus; if the value is true, the button press is passed to the 
client window or used to do a window management operation, if appropriate. 
The keyboard input focus selection is done in either case. The default value 
for this resource is true. 

posltionlsFrame (class PositionlsFrame) 

This resource indicates how client window position information (from the 
WM_NORMAL_HINTS property and from configuration requests) is to be 
interpreted. If the resource value is true then the information is interpreted as 
the position of the mwm client window frame. If the value is false then it is 
interpreted as being the position of the client area of the window. The default 
value of this resource is true. 

positionOnScreen (class PositionOnScreen) 

This resource is used to indicate that windows should initially be placed 
(if possible) so that they are not clipped by the edge of the screen (if the 
resource value is true). If a window is larger then the size of the screen then 
at least the upper left corner of the window will be on-screen. If the resource 
value is false, then windows are placed in the requested position even if 
totally off-screen. The default value of this resource is true. 

quitTimeout (class QuitTimeouf) 

This resource specifies the amount of time (in milliseconds) that mwm will 
wait for a client to update the WM_COMMAND property after mwm has sent 
the WM_SAVE_YOURSELF message. This protocol will only be used for 
those clients that have a WM_SAVE_YOURSELF atom and no 
WM_DELETE_WINDOW atom in the WM_PROTOCOLS client window 
property. The default value of this resource is 1000 ms. (Refer to the f -kill 
function for additional information.) 

resizeBorderWidth (class ResizeBorderWidth) 

This resource specifies the width (in pixels) of a client window frame 
border with resize handles. The specified border width includes the 3-D 
shadows. The default is 10 pixels. 

resizeCursors (class ResizeCursors) 

This is used to indicate whether the resize cursors are always displayed 
when the pointer is in the window size border. If true, the cursors are shown, 
otherwise the window manager cursor is shown. The default value is true. 
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show/Feedback (class Show/Feedback) 



c 

This resource controls when feedback information is displayed. It 
controls both window position and size feedback during move or resize 
operations and initial client placement. It also controls window manager 
message and dialog boxes. The value for this resource is a list of names of the 
feedback options to be enabled; the names must be separated by a space. The 
names of the feedback options are shown below: 



Name 


Description 


all 


Show all feedback. (Default value.) 


behavior 


Confirm behavior switch. 


move 


Show position during move. 


none 


Show no feedback. 


placement 


Show position and size during initial placement 


resize 


Show size during resize. 


restart 


Confirm mwm restart. 



The following command line illustrates the syntax for showFeedback: 

Mwm*showFeedhack: placement resize behavior restart 

This resource specification provides feedback for initial client placement 
and resize, and enables the dialog boxes to confirm the restart and set 
behavior functions. It disables feedback for the move function. 

startupKeyFocm (class StartupKeyFocus) 

This resource is only available when the keyboard input focus policy is 
explicit. When given the default value of true, a window gets the keyboard 
input focus when the window is mapped (i.e., initially managed by the 
window manager). 

transientDecoration (class TransientDecoration) 

This controls the amount of decoration that Mwm puts on transient 
windows. The decoration specification is exactly the same as for the 
clientDecoration (client specific) resource. Transient windows are identified 
by the WM_TRANSlENT_FOR property which is added by the client to 
indicate a relatively temporary window. The default value for this resource is 
menu title (i.e., transient windows will have resize borders and a ritlebar with 
a window menu button). 

translentFunctions (class TransientFunctions) 

This resource is used to indicate which window management functions 
are applicable (or not applicable) to transient windows. The function 
specification is exactly the same as for the cUentFunctions (client specific) 
resource. The default value for this resource is -minimize -maximize. 
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uselconBox (class UselconBox) 

If this resource is given a value of true, icons are placed in an icon box. 
When an icon box is not used, the icons are placed on the root window 
(default value). 

wMenuButtonClick (class WMenuButtonCUck) 

This resource indicates whether a click of the mouse when the pointer is 
over the window menu button will post and leave posted the system menu. If 
the value given this resource is true, then the menu will remain posted. True 
is the default value for this resource. 

wMenuButtonCUck2 (class WMenuButtonCUck2) 

When this resource is given the default value of true, a double-click action 
on the window menu button will do an f.kill function. 

• Specifying Client Specific Resources 

The syntax for specifying client specific resources is 

Mvim*client_name_or_class*resourceJd 

For example, Mwm*mterm*windowMenu is used to specify the window 
menu to be used with mterm clients. The syntax for specifying client specific 
resources for all classes of clients is 
Mwm*resource_/d 

Specific client specifications take precedence over the specifications for 
all clients. For example, Mwm* windowMenu is used to specify the window 
menu to be used for all classes of clients that don't have a window menu 
specified. The syntax for specifying resource values for windows that have an 
unknown name and class (i.e. the window does not have a WM_CLASS 
property associated with it) is 

Mwm'defaults* resource Jd 

For example, Mwm*defaults* iconlmage is used to specify the icon 
image to be used for windows that have an unknown name and class. The 
following client specific resources can be used. 
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Client Specific Resources 




Name 


Class Value Tvpe 


Default 


clientDecoration 


ClientDecoration 


string 


all 


clientFunctions 


CiientFunctions 


string 


all 


focusAutoRaise 


FocusAutoRaise 


T/F 


T 


iconlmage 


iconlmage 


pathname(image) 


IconlmageBackground 


Background 


color 


icon background 


iconlmageBottomShadowColor 


Foreground 


color 


icon bottom shadow 


iconlmageBottomShadowPixmap 


BottomShadowPixmap 


color 


icon bottom shadow 
pixmap 


IconlmageForeground 


Foreground 


color 


icon foreground 


IconlmageTopShadowColor 


Background 


color 


icon top shadow color 


iconlmageTopShadowPlxmap 


TopShadowPixmap 


color 


icon top shadow 
pixmap 


matteBackground 


Background 


color 


background 


matteBottomShadowColor 


Foreground 


color 


bottom shadow color 


matteBottomShadowPixmap 


BottomShadowPixmap 


color 


bottom shadow 
pixmap 


matteForeground 


Foreground 


color 


foreground 


matteTopShadowColor 


Background 


color 


top shadow color 


matteTopShadowPixmap 


TopShadowPixmap 


color 


top shadow pixmap 


matteWidth 


MatteWidth 


pixels 





maximumClientSize 


MaximumClientSize 


wxh 


fill the screen 


useClientlcon 


UseClientlcon 


T/F 


F 


windowMenu 


WindowMenu 


string 


string 



clientDecoration (class ClientDecoration) 

This resource controls the amount of window frame decoration. The 
resource is specified as a list of decorations which can be included in the 
frame. If a decoration is preceded by a minus sign, then that decoration is 
excluded from the frame. The sign of the first item in the list determines the 
initial amount of decoration. If the sign of the first decoration is minus, then 
mwm assumes all decorations are present and starts subtracting from that set. 
If the sign of the first decoration is plus (or not specified), then mwm starts 
with no decoration and builds up a list from the resource. 

Name Description 

all Include all decorations (default value) 

border Window border 

maximize Maximize button (includes title bar) 

minimize Minimize button (includes title bar) 

none No decorations 

resizeh Border resize handles (includes border) 

menu Window menu button (includes title bar) 

title Title bar (includes border) 

Examples: 

Mwm*XCIock.clientDecoration: -resizeh -maximize 



c 



3-44 



ESV Workstation Reference Manual [2.0] 



X Clients 



This removes the resize handles and maximize button from XCIock 
windows. 

Mwm'XClock.clientDecoration: menu minimize border 

This does the same thing as above. Note that either menu or minimize 
implies title. 

clientFunctions (class ClientFunctions) 

This resource is used to indicate which mwm functions are applicable (or 
not applicable) to the client window. The value for the resource is a list of 
functions. If the first function in the list has a minus sign in front of it, then 
mwm starts with all functions and subtracts from that set. If the first function 
in the list has a plus sign in front of it, then mwm starts with no functions and 
builds up a list. Each function in the list must be preceded by the appropriate 
plus or minus sign and be separated from the next function by a space. The 
table below lists the functions available for this resource. 



Name 


Description 


ail 


Include all functions (default value) 


none 


No functions 


resize 


f.resize 


move 


f.move 


minimize 


f.minimize 


maximize 


f.maximize 


close 


f.kill 



focusAutoRaise (class FocusAutoRaise) 

When the value of this resource is true, clients are made completely 
unobscured when they get the keyboard input focus. If the value is false, the 
stacking of windows on the display is not changed when a window gets the 
keyboard input focus. The default value is true. 

iconlmage (class Iconlmage) 

This resource can be used to specify an icon image for a client {e.g., 
Mwm*myclock*/con//naflfe). The resource value is a pathname for a bitmap 
file. The value of the (client specific) useClientlcon resource is used to 
determine whether or not user supplied icon images are used instead of client 
supplied icon images. The default value is to display a built-in window 
manager icon image. 

iconlmageBackground (class Background) 

This resource specifies the background color of the icon image that is 
displayed in the image part of an icon. The default value of this resource is 
the icon background color (i.e., specified by Mwm* background or 
Mwm*icon* background). 
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iconlmageBottomShadowColor (class Foreground) 

This resource specifies the bottom shadow color of the icon image that is 
displayed in the image part of an icon. The default value of this resource is 
the icon bottom shadow color (i.e., specified by 
fAYJir\*\con k bottomShadowColor). 

iconimageBottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the icon image that 
is displayed in the image part of an icon. The default value of this resource is 
the icon bottom shadow Pixmap. 

iconlmageForeground (class Foreground) 

This resource specifies the foreground color of the icon image that is 
displayed in the image part of an icon. The default value of this resource is 
the icon foreground color (i.e., specified by Mwm* foreground or 
Nlvim*\con*foreground). 

IconfmageTopShadowCoior (class Background) 

This resource specifies the top shadow color of the icon image that is 
displayed in the image part of an icon. The default value of this resource is 
the icon top shadow color. 

IconlmageTopShadowPIxmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the icon image that is dis- 
played in the image part of an icon. The default value of this resource is the 
icon top shadow Pixmap (i.e., specified by Mwm*icon* topShadowPixmap). 

matteBackground (class Background) 

This resource specifies the background color of the matte, when 
matteWidth is positive. The default value of this resource is the client 
background color (i.e., specified by Mwm* background or 
Mwm*client* background). 

matteBottomShadowColor (class Foreground) 

This resource specifies the bottom shadow color of the matte, when 
matteWidth is positive. The default value of this resource is the client bottom 
shadow color (i.e., specified by Mwm* bottomShadowCoior or 
Mvin\*cl\ent*bottomShadowColor). 

matteBottomShadowPixmap (class BottomShadowPixmap) 

This resource specifies the bottom shadow Pixmap of the matte, when 
matteWidth is positive. The default value of this resource is the client bottom 
shadow Pixmap. 



C 
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matteForeground (class Foreground) 

This resource specifies the foreground color of the matte, when 
matteWidth is positive. The default value of this resource is the client 
foreground color (i.e., specified by Mwm * foreground or 
Mwm*client* foreground). 

matteTopShadowColor (class Background) 

This resource specifies the top shadow color of the matte, when 
matteWidth is positive. The default value of this resource is the client top 
shadow color (i.e., specified by Mwm* topShadowColor or 
Mwm *cl lent* topShadowColor). 

matteTopShadowPixmap (class TopShadowPixmap) 

This resource specifies the top shadow Pixmap of the matte, when 
matteWidth is positive. The default value of this resource is the client top 
shadow Pixmap. 

matteWidth (class MatteWidth) 

This resource specifies the width of the optional matte. The default value 
is 0, which effectively disables the matte. 

maximumClientSize (class MaximumCiientSize) 

This is a size specification indicating the client size to be used when an 
application is maximized. The resource value is specified as widthxheight. 
The width and height are interpreted in the units that the client uses (e.g., for 
terminal emulators this is generally characters). If this resource is not 
specified then the maximum size from the WM_NORM AL_HINTS property is 
used, if it has been set. Otherwise the default value is the size where the client 
window with window management borders fills the screen. When the 
maximum client size is not determined by the maximumClientSizeresourcQ, 
the MaximumSize resource value is used as a constraint on the maximum 
size. 

usedientlcon (class UseClientfcon) 

If the value given for this resource is true, a client supplied icon image 
will take precedence over a user supplied icon image. The default value is 
false, making the user supplied icon image have higher precedence than the 
client supplied icon image. 

windowMenu (class WindowMenu) 

This resource indicates the name of the menu pane that is posted when the 
window menu is popped up (usually by pressing button 1 on the window 
menu button on the client window frame). Menu panes are specified in the 
mwm resource description file. Window menus can be customized on a client 
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class basis by specifying resources of the form 
Mmy\*cIient_name_ot_class*windowMenu (see "mwm Resource 
Description File Syntax" below). The default value of this resource is the 
name of the built-in window menu specification. 

Resource Description File 

The mwm resource description file is a supplementary resource file that con- 
tains resource descriptions referred to by entries in the defaults files (.Xde- 
faults, app-defaults/Mwm). It contains descriptions of resources that are to 
be used by mwm, and that cannot be easily encoded in the defaults files (a 
bitmap file is an analogous type of resource description file). A particular 
mwm resource description file can be selected using the configFile resource. 
The following types of resources can be described in the mwm resource de- 
scription file: 

• Buttons 

Window manager functions can be bound (associated) with button 
events. 

• Keys 

Window manager functions can be bound (associated) with key press 
events. 

• Menus 

Menu panes can be used for the window menu and other menus posted 
with key bindings and button bindings. 

mwm Resource Description File Syntax 

The mwm resource description file is a standard text file that contains items 
of information separated by blanks, tabs, and new lines characters. Blank 
lines are ignored. Items or characters can be quoted to avoid special interpre- 
tation (e.g., the comment character can be quoted to prevent it from being in- 
terpreted as the comment character). A quoted item can be contained in dou- 
ble quotes ("). Single characters can be quoted by preceding them by the 
back-slash character (\). All text from an unquoted pound sign (#) to the end 
of the line is regarded as a comment and is not interpreted as part of a resource 
description. If an exclamation point (!) is the first character in a line, the line 
is regarded as a comment. Window manager functions can be accessed with 
button and key bindings, and with window manager menus. Functions are in- 
dicated as part of the specifications for button and key binding sets, and menu 
panes. The function specification has the following syntax: 

function = function_name [function_args] 
fimction_name = window manager function 
function_args ={ quo ted_i tern | unquoted_item} 
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The following functions are supported. If a function is specified that isn't 
one of the supported functions then it is interpreted by mwm as f .nop. 

f.beep 

This function causes a beep. 

f.circle_down [icon / window] 

This function causes the window or icon that is on the top of the window 
stack to be put on the bottom of the window stack (so that it is no longer 
obscuring any other window or icon). This function affects only those 
windows and icons that are obscuring other windows and icons, or that are 
obscured by other windows and icons. Secondary windows (i.e. transient 
windows) are restacked with their associated primary window. Secondary 
windows always stay on top of the associated primary window and there can 
be no other primary windows between the secondary windows and then- 
primary window. If an icon function argument is specified, then the function 
applies only to icons. If a window function argument is specified then the 
function applies only to windows. 

f.circle_up [icon / window] 

This function raises the window or icon on the bottom of the window 
stack (so that it is not obscured by any other windows). This function affects 
only those windows and icons that are obscuring other windows and icons, or 
that are obscured by other windows and icons. Secondary windows (i.e. 
transient windows) are restacked with their associated primary window. If an 
icon function argument is specified then the function applies only to icons. If 
a window function argument is specified then the function applies only to 
windows. 

f .exec or I 

This function causes command to be executed (using the value of the 
$SHELL environment variable if it is set, otherwise /bin/sh). The ! notation 
can be used in place of the f .exec function name. 

f.focus_color 

This function sets the colormap focus to a client window. If this function 
is done in a root context, then the default colormap (setup by the X Window 
System for the screen where mwm is running) is installed and there is no 
specific client window colormap focus. This function is treated as f.nop if 
colormapFocusPolicyis not explicit. 

f.focus_key 

This function sets the keyboard input focus to a client window or icon. 
This function is treated as f.nop if key boardFocusPoiicy is not explicit or 
the function is executed in a root context. 
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f.kill 

If the WM_DELETE_WINDOW protocol is set up, the client is sent a 
client message event indicating that the client window should be deleted. If 
the WM_SAVE_YOURSELF protocol is set up and the 
WM_DELETE__WINDOW protocol is not set up, the client is sent a client 
message event indicating that the client needs to prepare to be terminated. If 
the client does not have the WM_DELETE_WINDOW or 
WM_SAVE_YOURSELF protocol set up, this function causes a client's X 
connection to be terminated (usually resulting in termination of the client). 
Refer to the description of the quItTlmeout resource and the 
WM_PROTOCOLS property. 

f .lower [-client] 

This function lowers a client window to the bottom of the window stack 
(where it obscures no other window). Secondary windows (i.e. transient 
windows) are restacked with their associated primary window. The client 
argument indicates the name or class of a client to lower. If the client 
argument is not specified then the context in which the function was invoked 
indicates the window or icon to lower. 

f.maximize 

This function causes a client window to be displayed at its maximum size. 

f.menu 

This function associates a cascading (pull-right) menu with a menu pane 
entry or a menu with a button or key binding. The menu_name function 
argument identifies the menu to be used. 

f.minimize 

This function causes a client window to be minimized (iconified). When 
a window is minimized and no icon box is used, its icon is placed on the 
bottom of the window stack (such that it obscures no other window). If an 
icon box is used, then the client's icon changes to its iconified form inside the 
icon box. Secondary windows (i.e. transient windows) are minimized with 
their associated primary window. There is only one icon for a primary 
window and all its secondary windows. 

f.move 

This function allows a client window to be interactively moved. 

f.next_cmap 

This function installs the next colormap in the list of colormaps for the 
window with the colormap focus. 
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f .next _key [icon / window / transient] 

This function sets the keyboard input focus to the next window/icon in the 
set of windows/icons managed by the window manager (the ordering of this 
set is based on the stacking of windows on the screen). This function is treated 
as f.nop if keyboardFocusPoiicy is not explicit. The keyboard input focus 
is only moved to windows which do not have an associated secondary 
window that is application modal. If the transient argument is specified, then 
transient (secondary) windows are traversed (otherwise, if only window is 
specified, traversal is done only to the last focused window in a transient 
group). If an icon function argument is specified, then the function applies 
only to icons. If a window function argument is specified, then the function 
applies only to windows. 

f.nop 

This function does nothing. 

{.normalize 

This function causes a client window to be displayed with its normal size. 
Secondary windows (i.e. transient windows) are placed in their normal state 
along with their associated primary window. 

f.packjcons 

This function is used to adjust the icon layout (based on the layout policy 
being used) on the root window or in the icon box. In general, this causes 
icons to be "packed" into the icon grid. 

f.pass_keys 

This function is used to enable/disable (toggle) processing of key 
bindings for window manager functions. When it disables key binding 
processing all keys are passed on to the window with the keyboard input focus 
and no window manager functions are invoked. If the f .passjceys function 
is invoked with a key binding to disable key binding processing, the same key 
binding can be used to enable key binding processing. 

f.post_wmenu 

This function is used to post the window menu. If a key is used to post the 
window menu and a window menu button is present, the window menu is 
automatically placed with its top-left corner at the bottom-left comer of the 
window menu button for the client window. If no window menu button is 
present, the window menu is placed at the top-left corner of the client 
window. 

f.prev_cmap 

This function installs the previous colormap in the list of colormaps for 
the window with the colormap focus. 
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f.prev_key [icon / window I transient] 

This function sets the keyboard input focus to the previous window/icon 
in the set of windows/icons managed by the window manager (the ordering 
of this set is based on the stacking of windows on the screen). This function 
is treated as f .nop if keyboardFocusPolicy is not explicit. The keyboard 
input focus is only moved to windows which do not have an associated 
secondary window that is application modal. If the transient argument is 
specified, then transient (secondary) windows are traversed (otherwise, if 
only window is specified, only the last focused window in a transient group 
is traversed). If an icon function argument is specified, the function applies 
only to icons. If a window function argument is spe&fied, the function 
applies only to windows. 

f.quit_mwm 

This function terminates mwm (but not the X window system). 

f.raise [-client] 

This function raises a client window to the top of the window stack (where 
it is obscured by no other window). Secondary windows (i.e. transient 
windows) are restacked with their associated primary window. The client 
argument indicates the name or class of a client to raise. If the client argument 
is not specified, the context in which the function was invoked indicates the 
window or icon to raise. 

f.raisejower 

This function raises a client window to the top of the window stack if it is 
partially obscured by another window, otherwise it lowers the window to the 
bottom of the window stack. Secondary windows (i.e. transient windows) are 
restacked with their associated primary window. 

f.refresh 

This function causes all windows to be redrawn. 

f.refresh__win 

This function causes a client window to be redrawn, 

f.resize 

This function allows a client window to be interactively resized. 

f.restart 

This function causes mwm to be restarted (effectively terminated and re- 
executed). 
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f.send_msg message__number 

This function sends a client message of the type 
_MOTIF_WM_MESSAGES with the message_type indicated by the 
message_numher function argument. The client message will only be sent 
if message_number is included in the client's _MOTIF_WM__MESSAGES 
property. A menu item label is grayed out if it is used to do an f .send_msg 
of a message that is not included in the client's _MOTIF_WM_M ESS AGES 
property. 

f .separator 

This function causes a menu separator to be put in the menu pane at the 
specified location (the label is ignored). 

f.set_behavior 

This function causes the window manager to restart with the default OSF 
behavior (if a custom behavior is configured) or a custom behavior (if an OSF 
default behavior is configured). 

f.title 

This function inserts a title in the menu pane at the specified location. 
Each function may be constrained as to which resource types can specify 
the function (e.g., menu pane) and also the context in which the function can 
be used (e.g., the function is done to the selected client window). Function 
contexts are 

• root 

No client window or icon has been selected as an object for the 
function. 

• window 

A client window has been selected as an object for the function. This 
includes the window's title bar and frame. Some functions are applied 
only when the window is in its normalized state (e.g., f.maximize) or 
its maximized state (e.g., f.normalize). 

• icon 

An icon has been selected as an object for the function. 

If a function is specified in a type of resource where it is not supported or 
is invoked in a context that does not apply then the function is treated as 
f .nop. The following table indicates the resource types and function contexts 
in which window manager functions apply. 
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Function 

f.beep 

f.circle_down 

f.circle_up 

f.exec 

f.focus_color 

f.focus_key 

f.kill 

f.lower 

f.maximize 

f.menu 

f.minimize 

f.move 

f.next_cmap 

f.next_key 

f.nop 

f.normalize 

f.packjcons 

f. pass keys 

f.post_wmenu 

f.prev_cmap 

f.prev_key 

f.quit_mwm 

f. raise 

f.raisejower 

f.refresh 

f.refresh_win 

f.resize 

f. restart 

f.sendjnsg 

f.separator 

f.set_behavior 

f.title 



Contexts 

root,lcon,wlndow 

root,icon,window 

root,icon,window 

root,icon,window 

root,lcon,window 

root,icon,window 

icon,window 

root, icon 5 window 

icon,window(normal) 

root,icon,window 

window 

icon,window 

root,icon,window 

root,icon,window 

root,icon,window 

icon,window(max) 

root,icon,window 

root,icon,window 

root,icon,window 

root,icon,window 

root,icon,window 

root 

root,icon,window 

icon,window 

root,icon,window 

window 

window 

root 

icon,window 

root,icon,window 

root, icon/window 

root, icon, window 



Resources 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

button,key,menu 

menu 

button,key,menu 

menu 



C 



Window Manager Event Specification 

Events are indicated as part of the specifications for button and key binding 
sets, and menu panes. 

Button events have the following syntax: 

button = [modif ier_list] <button_event_name> 
modif ier_list = modif ier_name {modif ier_name} 

AU modifiers specified are interpreted as being exclusive (this means that 
only the specified modifiers can be present when the button event occurs). 
The following table indicates the values that can be used for modifier_name. 
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The ALT key is frequently labeled EXTEND or META. ALT and META can be 
used interchangeably in event specification. 

Modifier Description 



CTRL 


Control Key 


SHIFT 


Shift Key 


ALT 


Alt/Meta Key 


META 


Meta/Alt Key 


LOCK 


Lock Key 


Modi 


Modifierl 


Mod2 


Modifier2 


Mod3 


Modifiers 


Mod4 


Modifier4 


Mod5 


Modifier5 



The following table indicates the values that can be used for 
button event name. 



Modifier 


Description 


Btn1 Down 


Button 1 Press 


BtnlUp 


Button 1 Release 


Btn1 Click 


Button 1 Press and Release 


Btn1Click2 


Button 1 Double Click 


Btn2Down 


Button 2 Press 


Btn2Up 


Button 2 Release 


Btn2CIIck 


Button 2 Press and Release 


Btn2Click2 


Button 2 Double Click 


Btn3Down 


Button 3 Press 


Btn3Up 


Button 3 Release 


BtnSCIick 


Button 3 Press and Release 


Btn3Click2 


Button 3 Double Click 


Btn4Down 


Button 4 Press 


Btn4Up 


Button 4 Release 


Btn4Click 


Button 4 Press and Release 


Btn4Click2 


Button 4 Double Click 


BtnSDown 


Button 5 Press 


Btn5Up 


Button 5 Release 


BtnSCIick 


Button 5 Press and Release 


Btn5Click2 


Button 5 Double Click 



Key events that are used by the window manager for menu mnemonics 
and for binding to window manager functions are single key presses; key 
releases are ignored. Key events have the following syntax: 

key = [modifier_list]<Key>key_name 

modifier list = modifier name {modif ier_name } 
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All modifiers specified are interpreted as being exclusive (this means that 
only the specified modifiers can be present when the key event occurs). 
Modifiers for keys are the same as those that apply to buttons. The key_name 
is an XI 1 keysym name. Keysym names can be found in the keysymdef.h 
file (remove the XK_ prefix). 

Button Bindings 

The buttonBindings resource value is the name of a set of button bindings 
that are used to configure window manager behavior. A window manager 
function can be done when a button press occurs with the pointer over a 
framed client window, an icon or the root window. The context for indicating 
where the button press applies is also the context for invoking the window 
manager function when the button press is done (significant for functions that 
are context sensitive). 

The button binding syntax is 

Buttons bindings_set__name 
{ 

button context function 
button context function 

button context function 
} 

The syntax for the context specification is 

context =ob ject [ | context] 

object =root | icon | window | title | frame | border | app 

The context specification indicates where the pointer must be for the 
button binding to be effective. For example, a context of window indicates 
that the pointer must be over a client window or window management frame 
for the button binding to be effective. The frame context is for the window 
management frame around a client window (including the border and 
titlebar), the border context is for the border part of the window management 
frame (not including the titlebar), the title context is for the title area of the 
window management frame, and the app context is for the application 
window (not including the window management frame). 

If an f .nop function is specified for a button binding, the button binding 
will not be done. 

Key Bindings 

The key Bindings resource value is the name of a set of key bindings that are 
used to configure window manager behavior. A window manager function 
can be done when a particular key is pressed. The context in which the key 
binding applies is indicated in the key binding specification. The valid con- 
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texts are the same as those that apply to button bindings. The key binding syn- 
tax is 

Keys bindings_set_name 

{ 

key context function 
key context function 



key context function 

} 

If an f .nop function is specified for a key binding, the key binding will not 
be done. If an f .post_wmenu or f .menu function is bound to a key, mwm 
will automatically use the same key for removing the menu from the screen 
after it has been popped up. 

The context specification syntax is the same as for button bindings. For 
key bindings, the frame, title, border, and app contexts are equivalent to the 
window context. The context for a key event is the window or icon that has 
the keyboard input focus (root if no window or icon has the keyboard input 
focus). 

Menu Panes 

Menus can be popped up using the f .post_wmenu and f .menu window man- 
ager functions. The context for window manager functions that are done from 
a menu is root, icon, or window depending on how the menu was popped up. 
In the case of the window menu or menus popped up with a key binding, the 
location of the keyboard input focus indicates the context. For menus popped 
up using a button binding, the context of the button binding is the context of 
the menu. The menu pane specification syntax is 

Menu menu_name 

{ 

label [mnemonic] [accelerator] function 
label [mnemonic] [accelerator] function 



label [mnemonic] [accelerator] function 

} 

Each line in the Menu specification identifies the label for a menu item 
and the function to be done if the menu item is selected. Optionally a menu 
button mnemonic and a menu button keyboard accelerator may be specified. 
Mnemonics are functional only when the menu is posted and keyboard 
traversal applies. 

The iabel may be a string or a bitmap file. The label specification has the 
following syntax: 
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label = text | bitmap_file ■ 

bitmap_file = @file_name V_ 

text = quoted_item | unquoted_item 
The string encoding for labels must be compatible with the menu font that 
is used. Labels are greyed out for menu items that do the f.nop function, an 
invalid function, or a function that doesn't apply in the current context. 

A mnemonic specification has the following syntax 

mnemonic = _character 
The first matching character in the label is underlined. If there is no 
matching character in the label, no mnemonic is registered with the window 
manager for that label. Although the character must exactly match a character 
in the label, the mnemonic will not execute if any modifier (such as SHIFT) 
is pressed with the character key. 

The accelerator specification is a key event specification with the same 
syntax as is used for key bindings to window manager functions. 

Environment 

mwm uses the environment variable $HOME specifying the user's home 
directory. 

Files 

/usr/lib/X11/system.mwmrc | 

/usr/lib/X1l/app-defaults/Mwm V 

$HOME/.Xdefaults $HOME/.mwmrc 

Copyright 

(c) Copyright 1989 by Open Software Foundation, Inc. 

(c) Copyright 1987, 1988, 1989 by Hewlett-Packard Company 

All rights reserved. 

Origin 

HP 

Related Information 

X(1) 

VendorSheli(3X) 

Xmlnstalilmage(3X) 
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